Interoperabilidade em Typescript

Introdução

Interoperabilidade no contexto do TypeScript significa: como o TS convive com código JS existente, bibliotecas de terceiros, e o ecossistema JavaScript como um todo, já que o mundo npm foi construído em JS puro, não em TS.

Problema central

Quando você instala uma biblioteca JS qualquer e tenta usá-la em Typescript, o compilador não sabe os tipos daquela biblioteca. Ele não consegue te ajudar com autocomplete, não detecta erros. É como usar o tipo any em tudo.

A solução são os arquivos de declaração de tipos — arquivos .d.ts. Eles descrevem a "forma" de uma biblioteca JS para o compilador TS, sem conter lógica nenhuma.

// exemplo simplificado de um .d.ts
declare function somar(a: number, b: number): number;
declare interface Config {
  timeout: number;
  retries?: number;
}

Você nunca executa esse arquivo. Ele é só um contrato que diz ao compilador: "essa biblioteca tem essa forma".

DefinitelyTyped — o repositório comunitário de tipos

A comunidade mantém um repositório enorme chamado DefinitelyTyped com tipos para milhares de bibliotecas JS populares. Você instala separadamente via npm:

npm install --save-dev @types/lodash
npm install --save-dev @types/node
npm install --save-dev @types/express

Hoje muitas bibliotecas já vêm com tipos embutidos (React, Zod, Prisma, etc.). As que não têm, provavelmente têm um @types/ disponível.

Misturando .ts e .js no mesmo projeto

O TypeScript permite isso — você não precisa migrar tudo de uma vez. No tsconfig.json

{
  "compilerOptions": {
    "allowJs": true,        // aceita arquivos .js no projeto
    "checkJs": false        // mas não tenta checar tipos neles
  }
}

Isso é muito útil na migração gradual de um projeto JS legado para TS. Você vai convertendo arquivo por arquivo, no seu ritmo.

any como válvula de escape

Quando você não tem tipos disponíveis e não quer criar um .d.ts, pode usar any para "desligar" a checagem naquele ponto:

const lib = require("alguma-lib-sem-tipos") as any;
lib.facaAlgumaCoisa(); // compilador não reclama

É um escape útil em situações pontuais, mas usar any em excesso derrota o propósito do TypeScript.

Uma alternativa melhor é unknown, que também aceita qualquer valor mas te obriga a checar o tipo antes de usar:

unknown como válvula de escape

Uma alternativa melhor é unknown, que também aceita qualquer valor mas te obriga a checar o tipo antes de usar:

function processar(valor: unknown) {
  if (typeof valor === "string") {
    console.log(valor.toUpperCase()); // aqui é seguro
  }
}