TypeScript
Creación y consumo de archivos .d.ts para describir módulos JavaScript, publicar tipos y separar declaraciones públicas de la implementación ejecutable.
Un archivo describe tipos y valores que existen en otro lugar. No contiene la implementación que se ejecutará.
.d.tsexport function calculateTotal(
items: readonly OrderItem[],
): number;JavaScript real → comportamiento
.d.ts → contrato para TypeScriptSi la declaration promete una API inexistente, el código compila y falla en runtime.
{
"compilerOptions": {
"declaration": true,
"declarationMap": true,
"emitDeclarationOnly": true,
"outDir": "dist"
}
}declaration genera .d.ts desde exports TypeScript.
export type Product = {
id: string;
name: string;
};
export function createProduct(
input: CreateProductInput,
): Product;Solo declaraciones exportadas y tipos alcanzables forman parte de la salida pública.
export const version = "1.0";En .d.ts se describe:
export const version: string;No se implementa el valor.
declare const applicationVersion: string;Indica que el valor existe en runtime por otra fuente.
Dentro de .d.ts, muchas declaraciones son ambient automáticamente y no necesitan repetir declare en cada export.
export function parseProduct(
value: unknown,
): Product;export class ProductService {
constructor(repository: ProductRepository);
load(id: string): Promise<Product>;
}Describe constructor, lado static y miembros públicos/protected. Los private fields pueden aparecer para preservar identidad, pero detalles privados no forman parte de la API consumible.
export interface ProductRepository {
save(product: Product): Promise<void>;
}No generan valores.
declare module "legacy-library" {
export function parse(value: string): unknown;
}Describe un módulo que el resolvedor encontrará en runtime.
Si una librería ofrece:
package
package/testing
package/adapters/nodesus exports y declarations deben describir esas entradas. Un único index.d.ts no arregla subpaths ausentes.
En paquetes Node modernos:
.d.mts describe un módulo ESM..d.cts describe un módulo CommonJS..d.ts se interpreta según el package scope y resolución.El formato debe corresponder con el JavaScript publicado.
{
"declarationMap": true
}Permiten que “Go to Definition” navegue desde .d.ts hacia fuente TypeScript cuando se publican los maps y sources adecuadamente.
/** @internal */
export function unsafeHelper() {}Con stripInternal, el compilador puede omitir declaraciones marcadas. No valida que la API restante no dependa de ellas; úsalo con cuidado y pruebas del package.
El compilador necesita poder expresar tipos públicos.
export const value = createComplexInternalValue();Con isolatedDeclarations, exports requieren anotaciones suficientes para generar .d.ts por archivo sin análisis completo.
export function parse(value: any): any;Propaga pérdida de seguridad a todos los consumidores. Usa generics, unknown o contratos específicos.
Si un export menciona un tipo de otra dependencia, esa dependencia forma parte del contrato de tipos. Debe estar disponible para consumidores, quizá como dependency o peerDependency.
DefinitelyTyped distribuye declarations bajo paquetes @types/* para librerías que no incluyen tipos.
El package debe corresponder con la versión de la librería runtime.
Un package puede compilar internamente y publicar .d.ts rotas. Prueba un proyecto consumidor real:
// src/index.ts
export { createClient } from "./client.js";
export type {
Client,
ClientOptions,
} from "./client.types.js";La build genera JS y declarations alineadas.
.d.ts..d.ts con formato distinto al JS..d.ts describe, no implementa.declaration genera contratos desde exports.¿Por qué añadir una función únicamente a un .d.ts no añade esa función a la librería?
Porque el archivo solo informa al checker; no genera la implementación JavaScript que el runtime debe encontrar.
Ambient declarations y global types describe valores proporcionados por el host sin imports normales.