Tipos de função em TypeScript: sintaxe de arrow e callbacks

Um tipo de função descreve os parâmetros e o valor de retorno de uma função, escrito com uma seta: (a: number, b: number) => number. Dê um nome a ele com type e você pode usá-lo em variáveis, parâmetros e propriedades de objeto.

type Operation = (a: number, b: number) => number;

const add: Operation = (a, b) => a + b;       // a and b are number
const multiply: Operation = (x, y) => x * y;  // names do not have to match

function apply(op: Operation, a: number, b: number): number {
  return op(a, b);
}

console.log(apply(add, 2, 3));      // 5
console.log(apply(multiply, 2, 3)); // 6

A função atribuída a add não precisa de anotações: os tipos dos parâmetros vêm de Operation. Isso se chama contextual typing, e é o principal motivo para dar nome a tipos de função.

Sintaxe de tipos de função

O formato é (parameters) => ReturnType. Cada parâmetro precisa de um nome e de um tipo. Os nomes estão ali para a leitura e para as dicas do editor; qualquer função com tipos de parâmetro compatíveis corresponde, seja qual for o nome que ela dá a eles.

type Predicate = (value: number) => boolean;
type Formatter = (value: number, digits?: number) => string; // optional parameter
type Logger = (...parts: string[]) => void;                    // rest parameter
type Factory = () => { id: number };                           // no parameters

O nome não é opcional. (string) => void declara um parâmetro chamado string sem tipo, e o strict mode o rejeita com TS7051: Parameter has a name but no type. Did you mean 'arg0: string'?. Escreva (value: string) => void.

Tipando arrow functions

Uma arrow function pode ser tipada de dois jeitos. Anote a própria função, ou anote a variável com um tipo de função e deixe os parâmetros serem inferidos.

// 1. Annotations on the function
const toCelsius = (f: number): number => ((f - 32) * 5) / 9;

// 2. A function type on the variable
const toFahrenheit: (c: number) => number = (c) => (c * 9) / 5 + 32;

// 3. The same, with a named type
type Convert = (value: number) => number;
const round1: Convert = (v) => Math.round(v * 10) / 10;

console.log(round1(toCelsius(100)));  // 37.8
console.log(toFahrenheit(37));        // 98.6

A forma 1 é a escolha usual para uma função avulsa. A forma 3 compensa quando várias funções compartilham uma assinatura (handlers, comparadores, conversores), porque a assinatura é escrita uma vez e uma mudança nela é verificada em todos os lugares.

Tipos de callback

Um parâmetro cujo tipo é um tipo de função é um callback. A função de quem chama é verificada contra ele, e os parâmetros dela são inferidos a partir dele.

function repeat(times: number, action: (index: number) => void): void {
  for (let i = 0; i < times; i++) action(i);
}

repeat(3, (i) => console.log("run", i));

function mapValues(values: number[], fn: (value: number, index: number) => string): string[] {
  const out: string[] = [];
  values.forEach((v, i) => out.push(fn(v, i)));
  return out;
}

// A callback may ignore trailing parameters: this one takes only value.
console.log(mapValues([1.5, 2.25], (v) => v.toFixed(1))); // [ '1.5', '2.3' ]

Duas regras deixam os callbacks agradáveis de usar:

• Menos parâmetros não tem problema. Uma função que recebe um parâmetro pode ser passada onde dois são oferecidos. O JavaScript ignora argumentos extras, então o TypeScript permite. Mais parâmetros do que o tipo oferece é erro (Target signature provides too few arguments.).
• Um retorno void aceita qualquer coisa. Um callback tipado como (...) => void pode retornar um valor; quem chama promete não usá-lo. É por isso que list.forEach((x) => other.push(x)) compila, mesmo que push retorne um número.

Os tipos dos parâmetros ainda precisam ser compatíveis. Passar (x: string) => ... onde (a: number, b: number) => number é esperado falha com Types of parameters 'x' and 'a' are incompatible.

Call signatures

(n: number) => string é uma abreviação de um tipo de objeto com uma call signature: { (n: number): string }. Você precisa da forma longa quando a função também carrega propriedades.

type Counter = {
  (): number;        // call signature: calling it returns a number
  count: number;     // and it has a property
  reset: () => void; // and a method
};

function makeCounter(): Counter {
  const fn = () => ++fn.count;
  fn.count = 0;
  fn.reset = () => { fn.count = 0; };
  return fn;
}

const next = makeCounter();
next();
next();
console.log(next(), next.count); // 3 3
next.reset();
console.log(next.count);         // 0

O TypeScript permite acrescentar propriedades a uma função declarada com const no mesmo escopo, e as acompanha no tipo da função. Uma interface também pode ter uma call signature: interface Counter { (): number; count: number }.

Uma construct signature descreve algo chamado com new. Ela acrescenta new na frente: new (name: string) => User, ou { new (name: string): User } na forma de objeto. É assim que você tipa um parâmetro que recebe uma classe.

Sintaxe de método vs sintaxe de propriedade

Em um tipo de objeto, um membro função pode ser escrito como método, handle(value: string): void, ou como uma propriedade que guarda uma função, handle: (value: string) => void. Parecem intercambiáveis, mas são verificados de forma diferente com strict:

// This does not compile: the property form checks parameters strictly.
interface WithMethod { handle(value: string | number): void }
interface WithProperty { handle: (value: string | number) => void }

const onlyStrings = (value: string) => console.log(value.toUpperCase());

const a: WithMethod = { handle: onlyStrings };   // accepted
const b: WithProperty = { handle: onlyStrings }; // rejected
a.handle(42);

O compilador mostra:

index.ts(8,27): error TS2322: Type '(value: string) => void' is not assignable to type '(value: string | number) => void'.
  Types of parameters 'value' and 'value' are incompatible.
    Type 'string | number' is not assignable to type 'string'.
      Type 'number' is not assignable to type 'string'.

O erro está certo: onlyStrings não consegue lidar com um número. A forma de método deixa o mesmo erro passar (os parâmetros de métodos são verificados de forma "bivariante" por razões históricas), e a.handle(42) quebraria em tempo de execução com TypeError: value.toUpperCase is not a function. Apague a linha do b para ver essa quebra. Quando você escreve seus próprios tipos de objeto, a forma de propriedade pega mais erros.

Evite o tipo Function

Function é o tipo nativo que todo valor função satisfaz. Quase nunca é o que você quer: o TypeScript não conhece os parâmetros nem o tipo de retorno, então toda chamada é aceita e retorna any.

const loose: Function = Math.max;
const result = loose("a", {});   // compiles: any arguments, result is any
console.log(result);             // NaN

const strict: (...values: number[]) => number = Math.max;
console.log(strict(3, 9, 4));    // 9
// @ts-expect-error: Argument of type 'string' is not assignable to parameter of type 'number'.
strict("a");

Troque Function pela assinatura real. Quando você realmente aceita qualquer função (um debounce genérico, um wrapper de log), (...args: never[]) => unknown aceita toda função e ainda mantém o resultado como unknown, e não any. Para funções cujos tipos dependem da entrada, veja generics: um tipo de função genérico fica assim: <T>(value: T) => T.