English 中文 العربية 日本語 Português

Promise<T> Tipos assíncronos

Última atualização: 2026-10-22

Promise<T> Tipos assíncronos

Os tipos assíncronos giram em torno de Promise<T>: o tipo de retorno de uma função async é automaticamente embrulhado em um Promise, e await o desembrulha no nível de valor; o tipo utilitário Awaited<T> faz o mesmo no nível de tipo (desembrulhando Promises aninhadas até o fim). Uma vez sabendo "que tipo vive dentro do Promise", cada variável no código assíncrono ganha um tipo preciso.

GrupoConfiguração e Prática
TipoSintaxe
Modo strictNão necessário

ℹ️ Info O editor transpila TypeScript para JavaScript e o executa (sem verificação de tipos); veja a Saída de cada exemplo para o resultado da verificação.

📝 Sintaxe

// funções async: o tipo de retorno é sempre embrulhado em Promise<T>
async function fetchUser(id: number): Promise<User> {
  const res = await getJson("/users/" + id); // await desenrola uma camada da Promise
  return res;                                 // o valor retornado é User
}

// Awaited<T>: await no nível dos tipos
type A = Awaited<Promise<User>>;        // User
type B = Awaited<Promise<Promise<User>>>; // User — aninhadas também são desenroladas até o fim

⚙️ Parâmetros

Promise<T>Um contêiner genérico nativo; T é o tipo do valor que se obtém eventualmente. Funciona com async/await de fábrica, sem importações
asyncModificador de função: permite await dentro; o valor de retorno é automaticamente embrulhado em um Promise — um T simples se torna Promise<T>, Promises existentes não são embrulhados duas vezes
Awaited<T>Tipo utilitário nativo que imita o await: desembrulha Promise<T>, desembrulha recursivamente o aninhamento e passa tipos não-Promise inalterados

Retorno：Uma função async retorna Promise<T>: quer o corpo retorne um T simples ou um Promise<T>, o tipo final é Promise<T> (nunca Promise<Promise<T>>).

▶ Exemplo

Edite o código abaixo e clique em Testar para ver o resultado transpilado:

Saída：

{"id":7,"title":"Write TypeScript notes","done":false}
todo#7 title="Write TypeScript notes" done=false

(Saída de execução após a transpilação; todo é inferido como Todo por meio do await — sem await, você segura um Promise<Todo>, e acessar todo.id diretamente é um erro de tipo)
▶ Testar

💡 Observações

ℹ️ Info Dentro de uma função async, return T e return Promise<T> são exatamente equivalentes — o tipo nunca se acumula em Promise<Promise<T>>; Awaited<T> é essa regra transformada em um tipo utilitário.
💡 Dica Promise.all produz uma tupla: Promise.all([p1, p2]) tem o tipo Promise<[A, B]>, preservando o tipo de cada posição — um único await obtém todos os valores com tipos individuais precisos.
⚠️ Atenção Um throw dentro de uma função async se torna um Promise rejeitado em vez de um throw síncrono: envolva o await em try/catch ou encadeie .catch(), senão você tem uma rejeição não tratada; o próprio tipo de retorno Promise<T> não revela a possível falha.
awaited returntype
Mais casos em breve.

📚 Tutoriais relacionados

Programação assíncrona e tipos no TypeScript
Lição 25: Programação assíncrona e tipos no TypeScript

❓ Perguntas frequentes

P O que Awaited<T> faz e quando ele é útil?
R Ele imita o await no nível de tipo: Promise<T> se torna T, Promises aninhados se desembrulham por completo, não-Promises passam inalterados. Raramente se usa diretamente — aparece mais dentro das tipagens nativas (Promise.all, tipos de retorno async) e em utilitários próprios que precisam desembrulhar um Promise, por exemplo Unwrap<T> = Awaited<T>.
P O que acontece se eu esquecer o await?
R Você segura um Promise<Todo>, não um Todo: acessar .id é um erro de tipo (mais óbvio sob strictNullChecks) e, em tempo de execução, é uma tarefa que não terminou. O TypeScript não fará o await por você — sempre que vir um tipo Promise, pergunte-se se precisa de await.
P Preciso escrever Promise<T> explicitamente para funções async?
R Não — a inferência deriva Promise<T> a partir das instruções return. Escrevê-lo explicitamente compensa em APIs públicas (o contrato fica visível e erros de assinatura aparecem primeiro); deixe funções internas pequenas inferirem.
Web-Tutorial.com

Equipe Técnica Web-Tutorial

Uma plataforma de tutoriais mantida por diversos desenvolvedores. Cada tutorial é escrito e revisado por profissionais da área correspondente. Trabalhamos para manter nosso conteúdo preciso e confiável — se encontrar algum problema, avise-nos.

100%