declare w TypeScript: pliki deklaracji .d.ts wyjaśnione

Plik deklaracji (.d.ts) zawiera typy i nic więcej: sygnatury, interfejsy i kształty klas dla JavaScriptu, który znajduje się gdzie indziej. Słowo kluczowe declare wykonuje to samo zadanie w zwykłym pliku. Mówi kompilatorowi „to istnieje w czasie działania, zaufaj mi” i nie emituje żadnego kodu.

declare const __APP_VERSION__: string; // a bundler would replace this

console.log(typeof __APP_VERSION__); // undefined: nothing defined it

try {
  console.log(__APP_VERSION__.length); // type checks, fails at run time
} catch (e) {
  console.log(e instanceof Error ? e.message : e);
}

Kompilator zaakceptował __APP_VERSION__.length, bo deklaracja mówi, że to napis. W czasie działania taka zmienna nie istnieje, więc odczyt .length rzuca ReferenceError: __APP_VERSION__ is not defined, czyli wyjątek, którego kompilator nie mógł przewidzieć. Tak wygląda umowa każdej deklaracji: typy są prawdziwe tylko w takim stopniu, w jakim prawdziwy jest stojący za nimi JavaScript.

Co trafia do pliku .d.ts

Najlepiej pokazuje to kompilacja z declaration: true. Z takiego kodu źródłowego:

// price.ts
export interface LineItem {
    name: string;
    price: number;
    qty: number;
}

const TAX = 0.2;

export function total(items: LineItem[]) {
    const sum = items.reduce((acc, item) => acc + item.price * item.qty, 0);
    return Math.round(sum * (1 + TAX) * 100) / 100;
}

export class Cart {
    private items: LineItem[] = [];
    add(item: LineItem) {
        this.items.push(item);
        return this;
    }
}

tsc zapisuje price.js i taki price.d.ts:

export interface LineItem {
    name: string;
    price: number;
    qty: number;
}
export declare function total(items: LineItem[]): number;
export declare class Cart {
    private items;
    add(item: LineItem): this;
}

Ciała funkcji zniknęły, wywnioskowane typy zwracane zostały wypisane (number, this), pole prywatne zachowało nazwę, ale straciło typ, a nieeksportowanego TAX w ogóle nie ma. Biblioteka publikuje .js dla Node i .d.ts dla twojego edytora i kompilatora. emitDeclarationOnly: true tworzy tylko pliki .d.ts, dla projektów, w których JavaScript buduje bundler.

Wbudowane elementy ES2022, których używasz na co dzień, też pochodzą z plików deklaracji: lib.es2022.d.ts i pokrewne pliki są dostarczane z TypeScriptem i wybierane przez target i lib.

Formy declare

Każda instrukcja declare opisuje coś, co już istnieje. W pliku .d.ts bez import i export (globalnym pliku deklaracji) każda z nich staje się widoczna w całym projekcie:

// globals.d.ts
declare const API_URL: string;                     // a global constant
declare let debugMode: boolean;                    // a global variable
declare function track(event: string, props?: Record<string, string>): void;
declare class Widget {                             // a class from a script tag
    constructor(el: string);
    render(): void;
}
declare namespace Analytics {                      // a global object
    function page(name: string): void;
}
declare module "legacy-charts" {                   // a module you import
    export function draw(data: number[]): void;
}

Wewnątrz pliku .d.ts interface i type nie potrzebują declare; każda inna deklaracja najwyższego poziomu bez declare albo export to błąd TS1046. Gdy plik ma import albo export, jego deklaracje są lokalne, a dodatki do zakresu globalnego trafiają do bloku declare global (pokazanego niżej). Zadeklarowana sygnatura to to, względem czego kompilator sprawdza wywołania:

// This does not compile: the declaration says every prop is a string.
declare function track(event: string, props?: Record<string, string>): void;

track("signup");
track("purchase", { items: 3 });

Kompilator zgłasza index.ts(5,21): error TS2322: Type 'number' is not assignable to type 'string'. Przekaż { items: "3" } albo zmień deklarację, jeśli prawdziwa funkcja przyjmuje liczby.

Pakiety @types

Wiele pakietów npm dostarcza własne pliki .d.ts, wskazane w polu types (albo w warunku types w exports) swojego package.json. Dla pakietów napisanych tylko w JavaScripcie projekt DefinitelyTyped, utrzymywany przez społeczność, publikuje typy w zakresie @types:

npm i lodash
npm i -D @types/lodash

Gdy importujesz (import) pakiet, TypeScript automatycznie szuka node_modules/@types/{name}. Typy, które opisują zmienne globalne, a nie import, takie jak @types/node (process, Buffer) albo describe i it z narzędzia do testów, muszą być wymienione w tsconfig.json:

{
    "compilerOptions": {
        "types": ["node"]
    }
}

Bez tego wpisu TypeScript 7 ich nie wczytuje, nawet gdy pakiet jest zainstalowany:

error TS2591: Cannot find name 'process'. Do you need to install type definitions for node? Try `npm i --save-dev @types/node` and then add 'node' to the types field in your tsconfig.

tsc --init zapisuje w nowej konfiguracji "types": [] z komentarzem, który dla projektów Node sugeruje ["node"].

Typowanie modułu bez typów

Import pakietu JavaScript, który nie ma typów ani w paczce, ani w @types, to błąd TS7016:

error TS7016: Could not find a declaration file for module 'fakelib'. '/project/node_modules/fakelib/index.js' implicitly has an 'any' type.

Napraw to plikiem .d.ts w dowolnym miejscu projektu (popularny jest folder types/; musi tylko być objęty przez include), który nie ma import ani export na najwyższym poziomie. Opisz części, których używasz:

// types/fakelib.d.ts
declare module "fakelib" {
    export function hi(name: string): string;
    export const version: string;
}

// Non-code files a bundler lets you import
declare module "*.svg" {
    const url: string;
    export default url;
}

Najkrótsza wersja, declare module "fakelib"; w jednej linii, sprawia, że każdy import z pakietu jest any. Usuwa błąd, a razem z nim wszystkie sprawdzenia, więc traktuj ją jako krok tymczasowy.

declare global

Kod, który dodaje coś do zakresu globalnego, na przykład polyfill, nowa metoda wbudowanego typu albo zmienna globalna ustawiana przez znacznik script, wymaga pasujących typów. Dodaje je declare global. Musi być w module (pliku z import lub export), dlatego na początku jest export {}:

export {}; // declare global only works in a module

declare global {
  interface Array<T> {
    last(): T | undefined;
  }
  var appName: string;
}

Array.prototype.last = function () {
  return this[this.length - 1];
};
globalThis.appName = "Inventory";

const prices = [4, 8, 15];
console.log(prices.last(), [].last(), appName); // 15 undefined Inventory

interface Array<T> łączy się z wbudowanym interfejsem Array zamiast go zastępować, a to właśnie var (nie let ani const) dodaje właściwość do globalThis. Rozszerzanie wbudowanych prototypów jest ryzykowne we współdzielonym kodzie; tą samą techniką declare global projekty dodają własne zmienne do process.env w interfejsie NodeJS.ProcessEnv z @types/node.

Rozszerzanie modułów

Żeby dodać coś do typów importowanego pakietu, zadeklaruj ponownie nazwę jego modułu i otwórz ponownie interfejs. Sam plik musi być modułem (załatwia to import; export {} też działa). Bez import ani export ten sam blok deklaruje zupełnie nowy moduł config-lib, który przesłania prawdziwe typy pakietu:

// types/config-lib.d.ts
import "config-lib";

declare module "config-lib" {
    interface Settings {
        beta: boolean; // merged into the package's own Settings interface
    }
}

Od tej pory load().beta z config-lib ma wszędzie typ boolean. Interfejsy się łączą, aliasy typów nie, więc żeby to zadziałało, biblioteka musi eksportować interface. W ten sposób wtyczki dodają pola do obiektów żądania albo konfiguracji frameworka.

skipLibCheck

skipLibCheck: true sprawia, że kompilator nie sprawdza typów w plikach .d.ts, także tych w node_modules. Twój własny kod nadal jest względem nich sprawdzany. Oszczędza to czas i pozwala uniknąć błędów z dwóch pakietów, których deklaracje sobie przeczą, dlatego tsc --init włącza tę opcję. Kosztem jest to, że błąd we własnych plikach .d.ts też nie zostanie zgłoszony.