Segredos de *.d.ts: como o TypeScript vê código alheio

Introdução: por que seu código "se dá bem" com lodash?

Você já se perguntou como o TypeScript descobre os tipos para uma biblioteca JavaScript comum como lodash ou jQuery? Afinal, você simplesmente escreve import _ from 'lodash', e de repente aparece autocompletar e verificação de tipos. Mágica? Não, é o trabalho dos misteriosos arquivos *.d.ts.

No Stack Overflow, a pergunta "About \"*.d.ts\" in TypeScript" acumulou milhares de visualizações — desenvolvedores querem entender o que está por trás dessa extensão. Hoje vamos olhar sob o capô do TypeScript e entender como funcionam as declarações de tipos. Você aprenderá não apenas a teoria, mas também obterá exemplos práticos que ajudarão a criar seus próprios tipos para qualquer projeto JavaScript.

O que é .d.ts na verdade?

Arquivos com a extensão .d.ts são arquivos de declaração do TypeScript. Eles contêm apenas descrições de tipos, mas não a implementação. Pense neles como um "contrato": o TypeScript olha para este arquivo e entende quais funções, classes e variáveis existem, e quais são seus tipos.

A diferença chave dos arquivos .ts comuns: .d.ts não é compilado para JavaScript. Eles existem apenas para análise estática e autocompletar.

// myLibrary.d.tsexport function greet(name: string): void;export const VERSION: string;

Agora, se você importar esta biblioteca, o TypeScript saberá: greet recebe uma string e não retorna nada, e VERSION é uma string. Sem este arquivo, você receberia o erro "Could not find a declaration file for module".

Como o TypeScript encontra .d.ts?

O mecanismo de busca de declarações funciona em várias etapas:

• Busca automática: Se ao lado de um arquivo .js houver um .d.ts com o mesmo nome, o TypeScript o pegará automaticamente.
• Campo types ou typings no package.json: Muitas bibliotecas indicam o caminho para seu arquivo de declarações. Por exemplo: "types": "./lib/index.d.ts".
• Diretiva /// <reference path="" />: Indicação manual do arquivo de declaração (método obsoleto, mas ainda encontrado).
• Pacotes @types: Se a biblioteca não contém seus próprios tipos, a comunidade os publica no npm com o nome @types/nome-da-biblioteca.

Quando você escreve npm install @types/react, você está baixando exatamente um conjunto de arquivos .d.ts que descrevem o React.

Sob o capô: como o TypeScript processa .d.ts

Vamos imaginar que o TypeScript é um detetive investigando o "caso dos tipos". Os arquivos .d.ts são os depoimentos das testemunhas. Eles dizem: "Aqui está a função add, ela recebe dois números e retorna um número". O TypeScript acredita nesses depoimentos e não verifica se é verdade (já que não há implementação).

Ambient declarations (declarações de ambiente)

Um dos recursos mais poderosos do .d.ts é a declaração de ambient modules. Isso permite descrever tipos para módulos que não existem no seu código. Por exemplo, você quer usar a variável global $ do jQuery:

// globals.d.tsdeclare var $: (selector: string) => any;

Ou descrever um módulo inteiro:

// my-custom-module.d.tsdeclare module 'my-custom-module' {    export function doSomething(x: number): string;    export interface Config {        timeout: number;    }}

Agora você pode escrever import { doSomething } from 'my-custom-module' — e o TypeScript saberá os tipos.

Tipos globais vs tipos de módulo

Uma diferença importante: arquivos .d.ts podem ser globais (se não tiverem import/export) ou modulares (se tiverem). Declarações globais são visíveis