Mais sobre Funções

Funções são o bloco básico de construção de qualquer aplicação, sejam elas funções locais, importadas de outro módulo ou métodos de uma classe. Elas também são valores e, assim como outros valores, o TypeScript tem várias formas de descrever como funções podem ser chamadas. Vamos aprender a escrever tipos que descrevem funções.

Expressões de Tipo de Função

A forma mais simples de descrever uma função é com uma expressão de tipo de função. Esses tipos são sintaticamente parecidos com arrow functions:

ts
function greeter(fn: (a: string) => void) {
fn("Hello, World");
}
 
function printToConsole(s: string) {
console.log(s);
}
 
greeter(printToConsole);
Try

A sintaxe (a: string) => void significa “uma função com um parâmetro, chamado a, do tipo string, que não tem valor de retorno”. Assim como nas declarações de função, se o tipo de um parâmetro não for especificado, ele é implicitamente any.

Observe que o nome do parâmetro é obrigatório. O tipo de função (string) => void significa “uma função com um parâmetro chamado string do tipo any“!

Claro, podemos usar um type alias para dar nome a um tipo de função:

ts
type GreetFunction = (a: string) => void;
function greeter(fn: GreetFunction) {
// ...
}
Try

Assinaturas de Chamada

Em JavaScript, funções podem ter propriedades além de serem chamáveis. No entanto, a sintaxe de expressão de tipo de função não permite declarar propriedades. Se quisermos descrever algo chamável que também tem propriedades, podemos escrever uma assinatura de chamada em um tipo objeto:

ts
type DescribableFunction = {
description: string;
(someArg: number): boolean;
};
function doSomething(fn: DescribableFunction) {
console.log(fn.description + " returned " + fn(6));
}
 
function myFunc(someArg: number) {
return someArg > 3;
}
myFunc.description = "default description";
 
doSomething(myFunc);
Try

Observe que a sintaxe é um pouco diferente da expressão de tipo de função: use : entre a lista de parâmetros e o tipo de retorno, em vez de =>.

Assinaturas de Construtor

Funções em JavaScript também podem ser invocadas com o operador new. O TypeScript chama essas funções de construtores, porque normalmente criam um novo objeto. Você pode escrever uma assinatura de construtor adicionando a palavra-chave new na frente de uma assinatura de chamada:

ts
type SomeConstructor = {
new (s: string): SomeObject;
};
function fn(ctor: SomeConstructor) {
return new ctor("hello");
}
Try

Alguns objetos, como o objeto Date do JavaScript, podem ser chamados com ou sem new. Você pode combinar assinaturas de chamada e de construtor no mesmo tipo da forma que quiser:

ts
interface CallOrConstruct {
(n?: number): string;
new (s: string): Date;
}
 
function fn(ctor: CallOrConstruct) {
// Passing an argument of type `number` to `ctor` matches it against
// the first definition in the `CallOrConstruct` interface.
console.log(ctor(10));
(parameter) ctor: CallOrConstruct (n?: number) => string
 
// Similarly, passing an argument of type `string` to `ctor` matches it
// against the second definition in the `CallOrConstruct` interface.
console.log(new ctor("10"));
(parameter) ctor: CallOrConstruct new (s: string) => Date
}
 
fn(Date);
Try

Funções Genéricas

É comum escrever uma função em que os tipos da entrada se relacionam com o tipo da saída, ou em que os tipos de duas entradas estão relacionados de alguma forma. Vamos considerar por um momento uma função que retorna o primeiro elemento de um array:

ts
function firstElement(arr: any[]) {
return arr[0];
}
Try

Essa função faz o trabalho, mas infelizmente tem o tipo de retorno any. Seria melhor se a função retornasse o tipo do elemento do array.

No TypeScript, genéricos são usados quando queremos descrever uma correspondência entre dois valores. Fazemos isso declarando um parâmetro de tipo na assinatura da função:

ts
function firstElement<Type>(arr: Type[]): Type | undefined {
return arr[0];
}
Try

Ao adicionar um parâmetro de tipo Type a essa função e usá-lo em dois lugares, criamos um vínculo entre a entrada da função (o array) e a saída (o valor de retorno). Agora, quando a chamamos, sai um tipo mais específico:

ts
// s is of type 'string'
const s = firstElement(["a", "b", "c"]);
// n is of type 'number'
const n = firstElement([1, 2, 3]);
// u is of type undefined
const u = firstElement([]);
Try

Inferência

Observe que não precisamos especificar Type neste exemplo. O tipo foi inferido (escolhido automaticamente) pelo TypeScript.

Também podemos usar vários parâmetros de tipo. Por exemplo, uma versão independente de map ficaria assim:

ts
function map<Input, Output>(arr: Input[], func: (arg: Input) => Output): Output[] {
return arr.map(func);
}
 
// Parameter 'n' is of type 'string'
// 'parsed' is of type 'number[]'
const parsed = map(["1", "2", "3"], (n) => parseInt(n));
Try

Observe que, neste exemplo, o TypeScript conseguiu inferir tanto o tipo do parâmetro de tipo Input (a partir do array de string fornecido) quanto o do parâmetro Output, com base no valor de retorno da expressão de função (number).

Restrições

Já escrevemos algumas funções genéricas que funcionam com qualquer tipo de valor. Às vezes queremos relacionar dois valores, mas só podemos operar sobre um subconjunto específico de valores. Nesse caso, podemos usar uma restrição para limitar os tipos que um parâmetro de tipo aceita.

Vamos escrever uma função que retorna o maior entre dois valores. Para isso, precisamos de uma propriedade length que seja um número. Ao restringir o parâmetro de tipo a esse formato, escrevemos uma cláusula extends:

ts
function longest<Type extends { length: number }>(a: Type, b: Type) {
if (a.length >= b.length) {
return a;
} else {
return b;
}
}
 
// longerArray is of type 'number[]'
const longerArray = longest([1, 2], [1, 2, 3]);
// longerString is of type 'alice' | 'bob'
const longerString = longest("alice", "bob");
// Error! Numbers don't have a 'length' property
const notOK = longest(10, 100);
Argument of type 'number' is not assignable to parameter of type '{ length: number; }'.2345Argument of type 'number' is not assignable to parameter of type '{ length: number; }'.
Try

Há algumas coisas interessantes a observar neste exemplo. Deixamos o TypeScript inferir o tipo de retorno de longest. A inferência do tipo de retorno também funciona em funções genéricas.

Como restringimos Type a { length: number }, podemos acessar a propriedade .length dos parâmetros a e b. Sem a restrição de tipo, não conseguiríamos acessar essas propriedades, porque os valores poderiam ser de algum outro tipo sem a propriedade length.

Os tipos de longerArray e longerString foram inferidos com base nos argumentos. Lembre-se: genéricos servem para relacionar dois ou mais valores de mesmo tipo!

Por fim, como esperávamos, a chamada longest(10, 100) é rejeitada porque o tipo number não tem a propriedade .length.

Trabalhando com Valores Restritos

Aqui está um erro comum ao trabalhar com restrições de tipos genéricos:

ts
function minimumLength<Type extends { length: number }>(
obj: Type,
minimum: number
): Type {
if (obj.length >= minimum) {
return obj;
} else {
return { length: minimum };
Type '{ length: number; }' is not assignable to type 'Type'. '{ length: number; }' is assignable to the constraint of type 'Type', but 'Type' could be instantiated with a different subtype of constraint '{ length: number; }'.2322Type '{ length: number; }' is not assignable to type 'Type'. '{ length: number; }' is assignable to the constraint of type 'Type', but 'Type' could be instantiated with a different subtype of constraint '{ length: number; }'.
}
}
Try

Pode parecer que essa função está correta: Type é restrito a { length: number }, e a função retorna Type ou um valor que atende a essa restrição. O problema é que a função promete retornar o mesmo tipo de objeto que foi passado, e não apenas algum objeto que atenda à restrição. Se esse código fosse válido, você poderia escrever um código que certamente não funcionaria:

ts
// 'arr' gets value { length: 6 }
const arr = minimumLength([1, 2, 3], 6);
// and crashes here because arrays have
// a 'slice' method, but not the returned object!
console.log(arr.slice(0));
Try

Especificando Argumentos de Tipo

O TypeScript normalmente consegue inferir os argumentos de tipo pretendidos em uma chamada genérica, mas nem sempre. Por exemplo, suponha que você escreveu uma função para combinar dois arrays:

ts
function combine<Type>(arr1: Type[], arr2: Type[]): Type[] {
return arr1.concat(arr2);
}
Try

Normalmente, seria um erro chamar essa função com arrays de tipos incompatíveis:

ts
const arr = combine([1, 2, 3], ["hello"]);
Type 'string' is not assignable to type 'number'.2322Type 'string' is not assignable to type 'number'.
Try

Se você pretende fazer isso, no entanto, pode especificar Type manualmente:

ts
const arr = combine<string | number>([1, 2, 3], ["hello"]);
Try

Diretrizes para Escrever Boas Funções Genéricas

Escrever funções genéricas é divertido, e é fácil se empolgar com parâmetros de tipo. Ter parâmetros de tipo demais, ou usar restrições onde elas não são necessárias, pode tornar a inferência menos eficiente e frustrar quem chama a sua função.

Empurre os Parâmetros de Tipo para Baixo

Aqui estão duas formas de escrever uma função que parecem semelhantes:

ts
function firstElement1<Type>(arr: Type[]) {
return arr[0];
}
 
function firstElement2<Type extends any[]>(arr: Type) {
return arr[0];
}
 
// a: number (good)
const a = firstElement1([1, 2, 3]);
// b: any (bad)
const b = firstElement2([1, 2, 3]);
Try

Essas funções podem parecer idênticas à primeira vista, mas firstElement1 é uma forma muito melhor de escrever essa função. O tipo de retorno inferido dela é Type, mas o de firstElement2 é any, porque o TypeScript precisa resolver a expressão arr[0] usando o tipo da restrição, em vez de “esperar” para resolver o elemento durante a chamada.

Regra: Sempre que possível, use o próprio parâmetro de tipo em vez de restringi-lo

Use Menos Parâmetros de Tipo

Aqui está outro par de funções parecidas:

ts
function filter1<Type>(arr: Type[], func: (arg: Type) => boolean): Type[] {
return arr.filter(func);
}
 
function filter2<Type, Func extends (arg: Type) => boolean>(
arr: Type[],
func: Func
): Type[] {
return arr.filter(func);
}
Try

Criamos um parâmetro de tipo Func que não relaciona dois valores. Isso é sempre um sinal de alerta, porque significa que quem quiser especificar argumentos de tipo precisa informar manualmente um argumento extra sem motivo. Func não faz nada além de tornar a função mais difícil de ler e de raciocinar sobre!

Regra: Use sempre o menor número possível de parâmetros de tipo

Parâmetros de Tipo Devem Aparecer Duas Vezes

Às vezes esquecemos que uma função pode não precisar ser genérica:

ts
function greet<Str extends string>(s: Str) {
console.log("Hello, " + s);
}
 
greet("world");
Try

Poderíamos ter escrito facilmente uma versão mais simples:

ts
function greet(s: string) {
console.log("Hello, " + s);
}
Try

Lembre-se: parâmetros de tipo servem para relacionar os tipos de múltiplos valores. Se um parâmetro de tipo aparece apenas uma vez na assinatura da função, ele não está relacionando nada. Isso inclui o tipo de retorno inferido: se Str fizesse parte do tipo de retorno inferido de greet, ele estaria relacionando o argumento e o retorno, e por isso seria usado duas vezes, mesmo aparecendo apenas uma vez no código escrito.

Regra: Se um parâmetro de tipo aparece em apenas um lugar, reconsidere com bastante cuidado se você realmente precisa dele

Parâmetros Opcionais

Funções em JavaScript muitas vezes recebem um número variável de argumentos. Por exemplo, o método toFixed de number recebe uma quantidade opcional de casas decimais:

ts
function f(n: number) {
console.log(n.toFixed()); // 0 arguments
console.log(n.toFixed(3)); // 1 argument
}
Try

Podemos modelar isso no TypeScript marcando o parâmetro como opcional com ?:

ts
function f(x?: number) {
// ...
}
f(); // OK
f(10); // OK
Try

Embora o parâmetro seja especificado com o tipo number, o parâmetro x terá, na prática, o tipo number | undefined, porque parâmetros não informados em JavaScript recebem o valor undefined.

Você também pode fornecer um valor padrão para o parâmetro:

ts
function f(x = 10) {
// ...
}
Try

Agora, no corpo de f, x terá o tipo number, porque qualquer argumento undefined será substituído por 10. Observe que, quando um parâmetro é opcional, quem chama sempre pode passar undefined, já que isso apenas simula um argumento “ausente”:

ts
// All OK
f();
f(10);
f(undefined);
Try

Parâmetros Opcionais em Callbacks

Depois de aprender sobre parâmetros opcionais e expressões de tipo de função, é muito fácil cometer os seguintes erros ao escrever funções que invocam callbacks:

ts
function myForEach(arr: any[], callback: (arg: any, index?: number) => void) {
for (let i = 0; i < arr.length; i++) {
callback(arr[i], i);
}
}
Try

O que as pessoas normalmente querem dizer ao escrever index? como parâmetro opcional é que ambas as chamadas abaixo sejam válidas:

ts
myForEach([1, 2, 3], (a) => console.log(a));
myForEach([1, 2, 3], (a, i) => console.log(a, i));
Try

O que isso realmente significa é que callback pode ser invocado com apenas um argumento. Em outras palavras, a definição da função diz que a implementação pode se parecer com isto:

ts
function myForEach(arr: any[], callback: (arg: any, index?: number) => void) {
for (let i = 0; i < arr.length; i++) {
// I don't feel like providing the index today
callback(arr[i]);
}
}
Try

Por consequência, o TypeScript vai aplicar esse significado e emitir erros que não são realmente possíveis:

ts
myForEach([1, 2, 3], (a, i) => {
console.log(i.toFixed());
'i' is possibly 'undefined'.18048'i' is possibly 'undefined'.
});
Try

Em JavaScript, se você chamar uma função com mais argumentos do que parâmetros, os argumentos extras são simplesmente ignorados. O TypeScript se comporta da mesma forma. Funções com menos parâmetros (dos mesmos tipos) sempre podem ocupar o lugar de funções com mais parâmetros.

Regra: Ao escrever um tipo de função para um callback, nunca escreva um parâmetro opcional, a menos que você pretenda chamar a função sem passar aquele argumento

Overloads de Função

Algumas funções em JavaScript podem ser chamadas com diferentes quantidades e tipos de argumentos. Por exemplo, você pode escrever uma função para produzir um Date que aceita um timestamp (um argumento) ou uma especificação de mês/dia/ano (três argumentos).

No TypeScript, podemos especificar uma função que pode ser chamada de diferentes formas escrevendo assinaturas de overload. Para isso, escreva algumas assinaturas de função (normalmente duas ou mais), seguidas do corpo da função:

ts
function makeDate(timestamp: number): Date;
function makeDate(m: number, d: number, y: number): Date;
function makeDate(mOrTimestamp: number, d?: number, y?: number): Date {
if (d !== undefined && y !== undefined) {
return new Date(y, mOrTimestamp, d);
} else {
return new Date(mOrTimestamp);
}
}
const d1 = makeDate(12345678);
const d2 = makeDate(5, 5, 5);
const d3 = makeDate(1, 3);
No overload expects 2 arguments, but overloads do exist that expect either 1 or 3 arguments.2575No overload expects 2 arguments, but overloads do exist that expect either 1 or 3 arguments.
Try

Neste exemplo, escrevemos dois overloads: um que aceita um argumento e outro que aceita três. Essas duas primeiras assinaturas são chamadas de assinaturas de overload.

Em seguida, escrevemos uma implementação da função com uma assinatura compatível. Funções têm uma assinatura de implementação, mas essa assinatura não pode ser chamada diretamente. Mesmo que tenhamos escrito uma função com dois parâmetros opcionais depois do obrigatório, ela não pode ser chamada com dois parâmetros!

Assinaturas de Overload e a Assinatura de Implementação

Esta é uma fonte comum de confusão. Muitas vezes, as pessoas escrevem código assim e não entendem por que há um erro:

ts
function fn(x: string): void;
function fn() {
// ...
}
// Expected to be able to call with zero arguments
fn();
Expected 1 arguments, but got 0.2554Expected 1 arguments, but got 0.
Try

De novo: a assinatura usada para escrever o corpo da função não pode ser “vista” de fora.

A assinatura da implementação não é visível de fora. Ao escrever uma função com overloads, você deve sempre ter duas ou mais assinaturas acima da implementação da função.

A assinatura de implementação também precisa ser compatível com as assinaturas de overload. Por exemplo, estas funções têm erros porque a assinatura de implementação não corresponde aos overloads de forma correta:

ts
function fn(x: boolean): void;
// Argument type isn't right
function fn(x: string): void;
This overload signature is not compatible with its implementation signature.2394This overload signature is not compatible with its implementation signature.
function fn(x: boolean) {}
Try
ts
function fn(x: string): string;
// Return type isn't right
function fn(x: number): boolean;
This overload signature is not compatible with its implementation signature.2394This overload signature is not compatible with its implementation signature.
function fn(x: string | number) {
return "oops";
}
Try

Escrevendo Bons Overloads

Assim como os genéricos, há algumas diretrizes que você deve seguir ao usar overloads de função. Seguir esses princípios vai tornar sua função mais fácil de chamar, de entender e de implementar.

Vamos considerar uma função que retorna o tamanho de uma string ou de um array:

ts
function len(s: string): number;
function len(arr: any[]): number;
function len(x: any) {
return x.length;
}
Try

Esta função está correta: podemos invocá-la com strings ou com arrays. No entanto, não podemos invocá-la com um valor que pode ser uma string ou um array, porque o TypeScript só consegue resolver uma chamada de função para um único overload:

ts
len(""); // OK
len([0]); // OK
len(Math.random() > 0.5 ? "hello" : [0]);
No overload matches this call. Overload 1 of 2, '(s: string): number', gave the following error. Argument of type 'number[] | "hello"' is not assignable to parameter of type 'string'. Type 'number[]' is not assignable to type 'string'. Overload 2 of 2, '(arr: any[]): number', gave the following error. Argument of type 'number[] | "hello"' is not assignable to parameter of type 'any[]'. Type 'string' is not assignable to type 'any[]'.2769No overload matches this call. Overload 1 of 2, '(s: string): number', gave the following error. Argument of type 'number[] | "hello"' is not assignable to parameter of type 'string'. Type 'number[]' is not assignable to type 'string'. Overload 2 of 2, '(arr: any[]): number', gave the following error. Argument of type 'number[] | "hello"' is not assignable to parameter of type 'any[]'. Type 'string' is not assignable to type 'any[]'.
Try

Como os dois overloads têm a mesma quantidade de argumentos e o mesmo tipo de retorno, podemos escrever uma versão sem overloads da função:

ts
function len(x: any[] | string) {
return x.length;
}
Try

Isso é muito melhor! Quem chama pode invocá-la com qualquer um dos dois tipos de valor e, como bônus, não precisamos descobrir uma assinatura de implementação correta.

Sempre prefira parâmetros com tipos união em vez de overloads, quando possível

Declarando this em uma Função

O TypeScript vai inferir qual deve ser o this em uma função por meio de análise de fluxo de código, por exemplo no caso a seguir:

ts
const user = {
id: 123,
 
admin: false,
becomeAdmin: function () {
this.admin = true;
},
};
Try

O TypeScript entende que a função user.becomeAdmin tem um this correspondente, que é o objeto externo user. this, he, he, pode ser suficiente para muitos casos, mas há muitas situações em que você precisa de mais controle sobre qual objeto o this representa. A especificação do JavaScript diz que você não pode ter um parâmetro chamado this, então o TypeScript usa essa posição de sintaxe para permitir que você declare o tipo de this no corpo da função.

ts
interface DB {
filterUsers(filter: (this: User) => boolean): User[];
}
 
const db = getDB();
const admins = db.filterUsers(function (this: User) {
return this.admin;
});
Try

Esse padrão é comum em APIs no estilo callback, em que outro objeto normalmente controla quando a sua função é chamada. Observe que você precisa usar function e não arrow functions para obter esse comportamento:

ts
interface DB {
filterUsers(filter: (this: User) => boolean): User[];
}
 
const db = getDB();
const admins = db.filterUsers(() => this.admin);
The containing arrow function captures the global value of 'this'.
Element implicitly has an 'any' type because type 'typeof globalThis' has no index signature.
7041
7017
The containing arrow function captures the global value of 'this'.
Element implicitly has an 'any' type because type 'typeof globalThis' has no index signature.
Try

Outros Tipos que Você Deve Conhecer

Há alguns tipos adicionais que você vai querer reconhecer, pois aparecem com frequência ao trabalhar com tipos de função. Como todos os tipos, você pode usá-los em qualquer lugar, mas estes são especialmente relevantes no contexto de funções.

void

void representa o valor de retorno de funções que não retornam um valor. É o tipo inferido sempre que uma função não tem nenhum return ou não retorna nenhum valor explícito nessas instruções:

ts
// The inferred return type is void
function noop() {
return;
}
Try

Em JavaScript, uma função que não retorna nenhum valor vai retornar implicitamente o valor undefined. No entanto, void e undefined não são a mesma coisa no TypeScript. Há mais detalhes no final deste capítulo.

void não é o mesmo que undefined.

object

O tipo especial object se refere a qualquer valor que não seja primitivo (string, number, bigint, boolean, symbol, null ou undefined). Ele é diferente do tipo objeto vazio { } e também é diferente do tipo global Object. É muito provável que você nunca vá usar Object.

object não é Object. Sempre use object!

Observe que, em JavaScript, valores de função são objetos: têm propriedades, têm Object.prototype na cadeia de protótipos, são instanceof Object, você pode chamar Object.keys neles, e assim por diante. Por esse motivo, tipos de função são considerados objects no TypeScript.

unknown

O tipo unknown representa qualquer valor. É semelhante ao tipo any, mas é mais seguro, porque não é válido fazer nada com um valor unknown:

ts
function f1(a: any) {
a.b(); // OK
}
function f2(a: unknown) {
a.b();
'a' is of type 'unknown'.18046'a' is of type 'unknown'.
}
Try

Isso é útil ao descrever tipos de função porque você pode descrever funções que aceitam qualquer valor sem ter valores any no corpo da função.

Por outro lado, você pode descrever uma função que retorna um valor de tipo unknown:

ts
function safeParse(s: string): unknown {
return JSON.parse(s);
}
 
// Need to be careful with 'obj'!
const obj = safeParse(someRandomString);
Try

never

Algumas funções nunca retornam um valor:

ts
function fail(msg: string): never {
throw new Error(msg);
}
Try

O tipo never representa valores que nunca são observados. Em um tipo de retorno, isso significa que a função lança uma exceção ou encerra a execução do programa.

never também aparece quando o TypeScript determina que não sobrou nada em uma união.

ts
function fn(x: string | number) {
if (typeof x === "string") {
// do something
} else if (typeof x === "number") {
// do something else
} else {
x; // has type 'never'!
}
}
Try

Function

O tipo global Function descreve propriedades como bind, call, apply e outras presentes em todos os valores de função em JavaScript. Ele também tem a propriedade especial de que valores do tipo Function podem sempre ser chamados; essas chamadas retornam any:

ts
function doSomething(f: Function) {
return f(1, 2, 3);
}
Try

Esta é uma chamada de função não tipada e, em geral, é melhor evitá-la por causa do tipo de retorno any, que não é seguro.

Se você precisa aceitar uma função arbitrária, mas não pretende chamá-la, o tipo () => void costuma ser mais seguro.

Parâmetros Rest e Argumentos

Leitura complementar:
Parâmetros rest
Sintaxe de spread

Parâmetros Rest

Além de usar parâmetros opcionais ou overloads para criar funções que aceitam uma variedade de quantidades fixas de argumentos, também podemos definir funções que recebem um número ilimitado de argumentos usando parâmetros rest.

Um parâmetro rest aparece depois de todos os outros parâmetros e usa a sintaxe ...:

ts
function multiply(n: number, ...m: number[]) {
return m.map((x) => n * x);
}
// 'a' gets value [10, 20, 30, 40]
const a = multiply(10, 1, 2, 3, 4);
Try

No TypeScript, a anotação de tipo desses parâmetros é implicitamente any[] em vez de any, e qualquer anotação de tipo informada deve ter a forma Array<T> ou T[], ou ser um tipo tupla (sobre o qual vamos aprender mais adiante).

Argumentos Rest

Por outro lado, podemos fornecer um número variável de argumentos a partir de um objeto iterável (por exemplo, um array) usando a sintaxe de spread. Por exemplo, o método push de arrays aceita qualquer número de argumentos:

ts
const arr1 = [1, 2, 3];
const arr2 = [4, 5, 6];
arr1.push(...arr2);
Try

Observe que, em geral, o TypeScript não assume que arrays são imutáveis. Isso pode levar a um comportamento surpreendente:

ts
// Inferred type is number[] -- "an array with zero or more numbers",
// not specifically two numbers
const args = [8, 5];
const angle = Math.atan2(...args);
A spread argument must either have a tuple type or be passed to a rest parameter.2556A spread argument must either have a tuple type or be passed to a rest parameter.
Try

A melhor correção para essa situação depende um pouco do seu código, mas, em geral, um contexto const é a solução mais direta:

ts
// Inferred as 2-length tuple
const args = [8, 5] as const;
// OK
const angle = Math.atan2(...args);
Try

Usar argumentos rest pode exigir ativar downlevelIteration ao compilar para runtimes mais antigos.

Desestruturação de Parâmetros

Leitura complementar:
Atribuição via desestruturação

Você pode usar a desestruturação de parâmetros para desempacotar de forma conveniente objetos fornecidos como argumento em uma ou mais variáveis locais no corpo da função. Em JavaScript, fica assim:

js
function sum({ a, b, c }) {
console.log(a + b + c);
}
sum({ a: 10, b: 3, c: 9 });

A anotação de tipo do objeto vai depois da sintaxe de desestruturação:

ts
function sum({ a, b, c }: { a: number; b: number; c: number }) {
console.log(a + b + c);
}
Try

Isso pode parecer um pouco verboso, mas você também pode usar um tipo nomeado aqui:

ts
// Same as prior example
type ABC = { a: number; b: number; c: number };
function sum({ a, b, c }: ABC) {
console.log(a + b + c);
}
Try

Compatibilidade de atribuição de funções

Tipo de retorno void

O tipo de retorno void para funções pode produzir alguns comportamentos incomuns, mas esperados.

A tipagem contextual com tipo de retorno void não obriga as funções a não retornarem nada. Dito de outra forma: um tipo de função contextual com retorno void (type voidFunc = () => void), quando implementado, pode retornar qualquer outro valor, mas esse valor será ignorado.

Assim, as seguintes implementações do tipo () => void são válidas:

ts
type voidFunc = () => void;
 
const f1: voidFunc = () => {
return true;
};
 
const f2: voidFunc = () => true;
 
const f3: voidFunc = function () {
return true;
};
Try

E quando o valor de retorno de uma dessas funções é atribuído a outra variável, ele mantém o tipo void:

ts
const v1 = f1();
 
const v2 = f2();
 
const v3 = f3();
Try

Esse comportamento existe para que o código a seguir seja válido, mesmo que Array.prototype.push retorne um número e o método Array.prototype.forEach espere uma função com tipo de retorno void.

ts
const src = [1, 2, 3];
const dst = [0];
 
src.forEach((el) => dst.push(el));
Try

Há mais um caso especial a conhecer: quando uma definição de função literal tem tipo de retorno void, essa função não deve retornar nada.

ts
function f2(): void {
// @ts-expect-error
return true;
}
 
const f3 = function (): void {
// @ts-expect-error
return true;
};
Try

Para saber mais sobre void, consulte estas outras entradas da documentação:

The TypeScript docs are an open source project. Help us improve these pages by sending a Pull Request ❤

Contributors to this page:
RCRyan Cavanaugh  (56)
OTOrta Therox  (15)
HAHossein Ahmadian-Yazdi  (4)
JWJoseph Wynn  (3)
UMDFUlisses, Mago do Flutter  (2)
39+

Last updated: Nov 16, 2026