Utility Types para Funções e Assincronismo: ReturnType, Parameters, ConstructorParameters e Awaited
Utility Types para Funções e Assincronismo: ReturnType, Parameters, ConstructorParameters e Awaited
ReturnType, Parameters, ConstructorParameters e desempacotar Promises recursivas com o moderno Awaited!
📑 Índice do Conteúdo
1. O Espaço de Tipos vs Espaço de Valores: A Regra do typeof
Antes de aplicar os utilitários de função, é vital compreender a fronteira fundamental entre o Espaço de Valores (Runtime) e o Espaço de Tipos (Compile-time) no TypeScript.
Uma função declarada com function processar() {} ou const log = () => {} existe no espaço de valores. Os Utility Types esperam receber um Tipo, não um valor. Portanto, para passar uma função como argumento para um Utility Type, você deve prefixá-la com o operador typeof:
ReturnType<minhaFuncao>, o compilador emitirá o erro fatal: TS2749: ‘minhaFuncao’ refers to a value, but is being used as a type here. Did you mean ‘typeof minhaFuncao’?. Lembre-se sempre: ReturnType<typeof minhaFuncao>!
2. ReturnType<T>: Extração Automática do Retorno de Funções
O ReturnType<T> examina o tipo de uma função e extrai cirurgicamente o tipo do valor retornado por ela:
// Fábrica de conexões com banco de dados
function criarPoolConexoes() {
return {
host: "db.webzoneware.internal",
porta: 5432,
conexoesAtivas: 12,
executarQuery: (sql: string) => ({ linhasAfetadas: 1, tempoMs: 14.2 }),
fecharConexao: () => true
};
}
// Em vez de criar manualmente a interface IPoolConexoes (duplicando o código),
// inferimos o tipo exato diretamente da função geradora:
type PoolBanco = ReturnType<typeof criarPoolConexoes>;
// Uso seguro com autocompletar e validação estática:
function monitorarBanco(pool: PoolBanco): void {
console.log(`Monitorando ${pool.host} na porta ${pool.porta}`);
}
3. Parameters<T>: Capturando a Tupla de Argumentos
O Parameters<T> extrai os tipos dos argumentos de uma função em formato de tupla fortemente tipada. Isso permite indexar posições específicas dos argumentos (Parameters<T>[0]) ou repassar a assinatura completa para wrappers e middlewares:
function enviarEmailTransacional(
destinatario: string,
assunto: string,
templateId: number,
metadados?: Record<string, string>
): boolean {
console.log(`Enviando para ${destinatario}: [${assunto}]`);
return true;
}
// 1. Extraindo a tupla completa de parâmetros:
// [destinatario: string, assunto: string, templateId: number, metadados?: Record | undefined]
type ArgumentosEmail = Parameters<typeof enviarEmailTransacional>;
// 2. Extraindo o tipo de um parâmetro isolado pelo índice posicional:
type TipoDestinatario = Parameters<typeof enviarEmailTransacional>[0]; // string
type TipoTemplateId = Parameters<typeof enviarEmailTransacional>[2]; // number
// 3. Criando uma função de fila assíncrona que espelha os parâmetros exatos:
function agendarEnvioEmailFila(...args: Parameters<typeof enviarEmailTransacional>): void {
console.log("Enfileirando mensagem com argumentos:", args);
// Dispara job no Redis / BullMQ...
}
// Autocomplete completo e checagem de tipos estrita preservada:
agendarEnvioEmailFila("[email protected]", "Sua Fatura Chegou", 109);
4. ConstructorParameters<T> e InstanceType<T>: Fábricas de Classes
Quando trabalhamos com Classes e Programação Orientada a Objetos, o TypeScript disponibiliza um par de utilitários correspondentes para inspecionar construtores:
ConstructorParameters<T>: Extrai a tupla de parâmetros exigida pelo métodoconstructorda classe.InstanceType<T>: Extrai o tipo da instância gerada pelo operadornewsobre aquela classe.
class ServicoNotificacaoPush {
constructor(
public readonly appId: string,
public readonly apiKey: string,
public readonly sandbox: boolean = false
) {}
public enviarNotificacao(deviceId: string, mensagem: string): void {
console.log(`Push enviado para ${deviceId}: ${mensagem}`);
}
}
// Tipo dos parâmetros do construtor: [appId: string, apiKey: string, sandbox?: boolean]
type ParametrosPush = ConstructorParameters<typeof ServicoNotificacaoPush>;
// Tipo da instância gerada: ServicoNotificacaoPush
type InstanciaPush = InstanceType<typeof ServicoNotificacaoPush>;
// Fábrica genérica universal (Inversão de Controle):
function fabricarInstancia<T extends new (...args: any[]) => any>(
ClasseAlvo: T,
...args: ConstructorParameters<T>
): InstanceType<T> {
console.log(`[FABRICA] Instanciando ${ClasseAlvo.name}...`);
return new ClasseAlvo(...args);
}
// O compilador exige os argumentos do construtor na ordem exata e com os tipos corretos!
const servico = fabricarInstancia(ServicoNotificacaoPush, "APP-998", "sec_live_key_xyz", true);
servico.enviarNotificacao("DEVICE-42", "Seu pedido saiu para entrega!");
5. Awaited<T>: Desempacotamento Profundo de Promises (TS 4.5+)
Em aplicações JavaScript modernas, a quase totalidade das operações com bancos de dados e redes é assíncrona. Se usarmos ReturnType<typeof buscarDados> em uma função assíncrona, obteremos Promise<Dados>.
Para obter os dados brutos desempacotados (o valor que o await retorna em tempo de execução), o TypeScript 4.5 introduziu o utilitário nativo Awaited<T>, que resolve recursivamente Promises aninhadas:
// Função assíncrona de busca de pedidos
async function consultarPedidoApi(codigoPedido: string) {
// Simula chamada de rede
return {
codigo: codigoPedido,
totalCentavos: 25990,
itens: ["Teclado Mecânico RGB", "Mousepad Extra Grande"],
statusEntrega: "EM_TRANSITO" as const
};
}
// 1. Usar apenas ReturnType resulta no envelope assíncrono:
type RespostaPromessa = ReturnType<typeof consultarPedidoApi>;
// Resultado: Promise
// 2. Com Awaited, desempacotamos o payload final resolvido:
type PedidoResolvido = Awaited<ReturnType<typeof consultarPedidoApi>>;
/*
Resultado perfeitamente desempacotado:
{
codigo: string;
totalCentavos: number;
itens: string[];
statusEntrega: "EM_TRANSITO";
}
*/
6. Exemplo Enterprise: Proxy de Cache Assíncrono com Decorator Funcional
Vejamos como uma arquitetura corporativa integra Parameters, ReturnType e Awaited em um utilitário de memorização/cache assíncrono universal que pode envelopar qualquer serviço da aplicação sem degradar a tipagem:
interface EntradaCache<T> {
dado: T;
expiracaoTimestamp: number;
}
// Wrapper de Cache fortemente tipado: preserva a assinatura original da função assíncrona
function criarCacheAssincrono<F extends (...args: any[]) => Promise<any>>(
funcaoOriginal: F,
tempoVidaMs: number
): (
...args: Parameters<F>
) => Promise<Awaited<ReturnType<F>>> {
const mapaCache = new Map<string, EntradaCache<Awaited<ReturnType<F>>>>();
return async (...args: Parameters<F>): Promise<Awaited<ReturnType<F>>> => {
const chaveCache = JSON.stringify(args);
const agora = Date.now();
const itemExistente = mapaCache.get(chaveCache);
if (itemExistente && itemExistente.expiracaoTimestamp > agora) {
console.log(`[CACHE HIT] Retornando valor em memória para args:`, args);
return itemExistente.dado;
}
console.log(`[CACHE MISS] Executando função de origem...`);
const resultado: Awaited<ReturnType<F>> = await funcaoOriginal(...args);
mapaCache.set(chaveCache, {
dado: resultado,
expiracaoTimestamp: agora + tempoVidaMs
});
return resultado;
};
}
// Testando o serviço de busca de taxas de câmbio:
async function cotarMoeda(origem: "USD" | "EUR", destino: "BRL"): Promise<{ taxa: number; data: string }> {
return { taxa: origem === "USD" ? 5.65 : 6.10, data: new Date().toISOString() };
}
// Função envelopada com cache de 60 segundos:
const cotarMoedaComCache = criarCacheAssincrono(cotarMoeda, 60000);
// Autocomplete perfeito dos parâmetros e do retorno!
cotarMoedaComCache("USD", "BRL").then(cotacao => {
console.log(`Taxa obtida: ${cotacao.taxa} em ${cotacao.data}`);
});
7. Armadilhas Comuns e Boas Práticas Sênior
- Funções com Sobrecargas (Function Overloads): Se você passar uma função que possui múltiplas sobrecargas para o
ReturnType, o TypeScript inferirá o retorno da última assinatura de sobrecarga declarada. Tenha atenção especial a isso em APIs legadas. - Cuidado com Funções Genéricas Não Instanciadas: Ao aplicar
ReturnType<typeof funcaoGenerica>, como os parâmetros genéricos não foram fornecidos, o compilador preencherá as variáveis de tipo comunknownou com suas restrições padrão. - Awaited vs Unwrap Manual: Não reinvente tipos condicionais manuais com
infer Upara extrair Promises em projetos modernos; use sempre oAwaited<T>nativo, pois ele trata perfeitamente uniões de Promises, tipos thenables e valores não-promessas.
Resumo da Lição 35 (Marco de 70% Concluído!)
- Funções existem no espaço de valores; para usá-las em Utility Types, utilize sempre
typeof. ReturnType<T>extrai o tipo retornado por uma função sem necessitar de interfaces auxiliares duplicadas.Parameters<T>captura os argumentos da função em uma tupla fortemente tipada.ConstructorParameters<T>eInstanceType<T>inspecionam classes e alimentam fábricas genéricas com IoC.Awaited<T>desempacota o valor final resolvido de Promises recursivas e tipos assíncronos.
📝 Exercício Prático Desafiador da Lição 35
Considere uma função de cálculo financeiro assíncrona de terceiros: async function calcularSimulacaoFinanciamento(valorImovel: number, parcelas: number, taxaJuros: number) { return { parcelaMensal: 3500.20, totalPago: 420000.00, aprovado: true }; }.
1. Crie o tipo ResultadoSimulacao utilizando Awaited e ReturnType para obter diretamente o objeto resolvido sem invocar a função.
2. Crie uma função genérica de debounce<F extends (...args: any[]) => any>(fn: F, atrasoMs: number): (...args: Parameters<F>) => void que aceite os mesmos parâmetros da função original e a invoque com temporizador.
Aplique o que você aprendeu nesta lição
Utilize nossas ferramentas online gratuitas para experimentar os conceitos ou teste o código ao vivo no Playground IDE.
Editor de Códigos Web Online
Ambiente com destaque de sintaxe para você testar tags, tabelas e scripts na hora.
Abrir Ferramenta OnlinePlayground Web Online
Escreva seu código HTML, CSS ou JavaScript e veja o resultado renderizado ao vivo no navegador com zero configuração.
⚡ Codificar no Playground IDE