`fișiere .d.ts` în TypeScript

Fișiere care conțin doar tipuri: descriu codul JavaScript ca să poată fi folosit din TypeScript cu verificare.

Sintaxă

// biblioteca.d.ts (sau .d.mts / .d.cts)
export declare function f(x: number): string;
export interface Optiuni { ... }

Ce face `fișiere .d.ts`

Un fișier de declarații (.d.ts) conține doar tipuri: semnături de funcții, interfețe, clase fără corp. Nu conține cod care rulează. Rolul lui este să descrie un fișier JavaScript, ca TypeScript să știe ce exportă și ce tipuri au funcțiile lui. Perechea preturi.mjs + preturi.d.mts se comportă pentru tsc ca un modul TypeScript.

Majoritatea pachetelor npm vin cu fișierele lor .d.ts (câmpul "types" din package.json). Pentru cele care nu au, tipurile sunt adesea publicate separat în proiectul DefinitelyTyped, ca pachete @types/nume (de exemplu @types/node). Fișierele lib.*.d.ts din TypeScript descriu JavaScript-ul însuși și browserul.

Când publici o bibliotecă scrisă în TypeScript, nu scrii .d.ts de mână: opțiunea declaration le generează din cod. Opțiunea skipLibCheck sare peste verificarea fișierelor .d.ts din node_modules, pentru compilare mai rapidă.

Exemple

Exemplul 1: Tipuri pentru un fișier JavaScript

preturi.mjs este JavaScript simplu. preturi.d.mts îi descrie exporturile, iar main.mts îl folosește cu verificare. Ultimul apel, cu un text, este eroare de compilare.

// preturi.mjs
export const TVA = 0.21;
export function cuTva(pret) {
    return Math.round(pret * (1 + TVA) * 100) / 100;
}

// preturi.d.mts
/** Cota standard de TVA din România. */
export declare const TVA: number;
/** Returnează prețul cu TVA, rotunjit la bani. */
export declare function cuTva(pret: number): number;

// main.mts
import { cuTva, TVA } from "./preturi.mjs";
console.log(`TVA ${TVA * 100}%: 100 lei devin ${cuTva(100)} lei`);
console.log(cuTva("100"));

Eroarea afișată de tsc

main.mts(4,19): error TS2345: Argument of type 'string' is not assignable to parameter of type 'number'.

Exemplul 2: Același program, fără ultimul rând

// main.mts (preturi.mjs și preturi.d.mts ca mai sus)
import { cuTva, TVA } from "./preturi.mjs";
console.log(`TVA ${TVA * 100}%: 100 lei devin ${cuTva(100)} lei`);

Rezultat (rulat cu tsc și node)

TVA 21%: 100 lei devin 121 lei

Exemplul 3: Fișier .d.mts generat cu –declaration

Pentru geometrie.mts, tsc --declaration --emitDeclarationOnly scrie doar tipurile. Tipul returnat de distanta (dedus) apare scris explicit, iar câmpul private apare fără tip.

// geometrie.mts
export interface Punct {
    x: number;
    y: number;
}
export function distanta(a: Punct, b: Punct) {
    return Math.hypot(a.x - b.x, a.y - b.y);
}
export const ORIGINE: Punct = { x: 0, y: 0 };
export class Cerc {
    constructor(public centru: Punct, private raza: number) {}
    arie() {
        return Math.PI * this.raza ** 2;
    }
}

Fișierul geometrie.d.mts generat

export interface Punct {
    x: number;
    y: number;
}
export declare function distanta(a: Punct, b: Punct): number;
export declare const ORIGINE: Punct;
export declare class Cerc {
    centru: Punct;
    private raza;
    constructor(centru: Punct, raza: number);
    arie(): number;
}

Greșeli frecvente

Scrii în .d.ts tipuri care nu corespund codului JavaScript. tsc nu poate verifica asta; greșelile apar la rulare.
Pui cod care rulează (const x = 5;) într-un .d.ts. Este eroare; acolo sunt permise doar declarații.
Instalezi @types/pachet pentru un pachet care are deja tipuri proprii. Cele două pot intra în conflict; verifică întâi câmpul types din package.json-ul pachetului.

Comenzi înrudite

declare: Anunță compilatorul că o variabilă, funcție sau modul există deja la rulare, fără să genereze cod pentru ea.
module și import/export: Fiecare fișier cu import sau export este un modul; exporți funcții, clase și tipuri și le imporți în alte fișiere.
tipuri pentru Node.js: Tipurile pentru modulele Node.js (fs, path, process…) vin din pachetul @types/node.
JSDoc cu tipuri: Tipuri scrise în comentarii JSDoc, ca TypeScript să verifice fișiere JavaScript fără să le transformi în .ts.
types: Alege exact ce pachete de tipuri globale (din node_modules/@types) se încarcă automat; [] nu încarcă niciunul.

Ce face fișiere .d.ts