Secretos de *.d.ts: cómo TypeScript ve el código de otros

Introducción: ¿por qué tu código «se lleva bien» con lodash?

¿Alguna vez te has preguntado cómo TypeScript conoce los tipos de una biblioteca JavaScript común como lodash o jQuery? Después de todo, simplemente escribes import _ from 'lodash' y de repente tienes autocompletado y verificación de tipos. ¿Magia? No, es el trabajo de los misteriosos archivos *.d.ts.

En Stack Overflow, la pregunta «About "*.d.ts" in TypeScript» ha acumulado miles de visitas: los desarrolladores quieren entender qué se esconde detrás de esta extensión. Hoy miraremos bajo el capó de TypeScript y analizaremos cómo funcionan las declaraciones de tipos. No solo aprenderás teoría, sino que también obtendrás ejemplos prácticos que te ayudarán a crear tus propios tipos para cualquier proyecto JavaScript.

¿Qué es realmente .d.ts?

Los archivos con la extensión .d.ts son archivos de declaración de TypeScript. Contienen solo descripciones de tipos, pero no la implementación. Piensa en ellos como un «contrato»: TypeScript mira este archivo y entiende qué funciones, clases y variables existen, y cuáles son sus tipos.

La diferencia clave con los archivos .ts normales: .d.ts no se compila a JavaScript. Existen solo para el análisis estático y el autocompletado.

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

Ahora, si importas esta biblioteca, TypeScript sabrá: greet acepta una cadena y no devuelve nada, y VERSION es una cadena. Sin este archivo, obtendrías el error «Could not find a declaration file for module».

¿Cómo encuentra TypeScript los .d.ts?

El mecanismo de búsqueda de declaraciones funciona en varias etapas:

• Búsqueda automática: Si junto a un archivo .js hay un .d.ts con el mismo nombre, TypeScript lo tomará automáticamente.
• Campo types o typings en package.json: Muchas bibliotecas indican la ruta a su archivo de declaración. Por ejemplo: "types": "./lib/index.d.ts".
• Directiva /// <reference path="" />: Indicación manual del archivo de declaración (método obsoleto, pero aún presente).
• Paquetes @types: Si la biblioteca no contiene sus propios tipos, la comunidad los publica en npm con el nombre @types/nombre-de-la-biblioteca.

Cuando escribes npm install @types/react, estás descargando precisamente un conjunto de archivos .d.ts que describen React.

Bajo el capó: cómo TypeScript procesa los .d.ts

Imaginemos que TypeScript es un detective que investiga el «caso de los tipos». Los archivos .d.ts son las declaraciones de los testigos. Dicen: «Aquí está la función add, acepta dos números y devuelve un número». TypeScript cree en estas declaraciones y no verifica si son realmente ciertas (ya que no hay implementación).

Ambient declarations (declaraciones ambientales)

Una de las capacidades más potentes de .d.ts es la declaración de ambient modules. Esto permite describir tipos para módulos que no existen en tu código. Por ejemplo, quieres usar la variable global $ de jQuery:

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

O describir un módulo completo:

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

Ahora puedes escribir import { doSomething } from 'my-custom-module' — y TypeScript conocerá los tipos.

Tipos globales vs tipos modulares

Una diferencia importante: los archivos .d.ts pueden ser globales (si no contienen import/export) o modulares (si los contienen). Las declaraciones globales se ven