Kurs JavaScript i TypeScript · Moduł 10: TypeScript w praktyce

Declaration files (.d.ts) i DefinitelyTyped

7 min czytania ·
W tej lekcji6

Wyobraź sobie, że w Parku Jurajskim odkryto starożytne tablice z opisami gatunków dinozaurów, napisane w nieznanym języku. Naukowcy musieli stworzyć słowniki, żeby zrozumieć, co te tablice opisują. W świecie TypeScript rolę takich słowników pełnią pliki deklaracji (.d.ts): opisują kształt kodu JavaScript, który sam nie ma informacji o typach. Bez nich biblioteka JavaScript jest dla kompilatora typem any (a w trybie strict import kończy się błędem), więc literówkę w nazwie metody odkryjesz dopiero w działającej aplikacji.

Czym są pliki .d.ts?

Pliki deklaracji (declaration files) to pliki z rozszerzeniem .d.ts, które zawierają wyłącznie informacje o typach, bez implementacji. Opisują kształt bibliotek JavaScript, modułów zewnętrznych i globalnych obiektów, a kompilator nie generuje z nich żadnego kodu. Oto opis biblioteki śledzącej dinozaury, w którym declare module 'nazwa' mówi, jak wygląda moduł importowany pod tą nazwą:

// plik: dinosaur-tracker.d.ts
// Opisujemy zewnętrzną bibliotekę JavaScript

declare module 'dinosaur-tracker' {
  export interface DinosaurPosition {
    id: string;
    species: string;
    latitude: number;
    longitude: number;
    lastSeen: Date;
  }

  export function trackDinosaur(id: string): DinosaurPosition;
  export function getAllPositions(): DinosaurPosition[];
  export function setAlert(species: string, radius: number): void;
}

Dzięki temu plikowi TypeScript wie, jakie funkcje i typy eksportuje moduł dinosaur-tracker, mimo że sam moduł jest napisany w czystym JavaScript. Implementacja nie zmieniła się ani o bajt, doszedł tylko opis. Gdy sam piszesz bibliotekę w TypeScript, takie pliki wygeneruje kompilator z opcją declaration: true.

Słowo kluczowe declare

Słowo declare informuje TypeScript: ten element istnieje w runtime, ale nie musisz go kompilować, po prostu mi zaufaj. Deklaracja nie tworzy kodu, więc jeśli skłamiesz, kompilator tego nie wykryje. Używamy jej do opisywania zmiennych, funkcji, klas i przestrzeni nazw.

Zmiennych globalnych

Skrypt wczytany tagiem <script> może ustawić globalną konfigurację parku. Opisujemy jej kształt, a nie wartość:

// Zmienna globalna dostępna w przeglądarce
declare const PARK_CONFIG: {
  name: string;
  maxCapacity: number;
  securityLevel: 'low' | 'medium' | 'high' | 'critical';
};

// Teraz możemy jej użyć z pełnym type safety
console.log(PARK_CONFIG.name);
console.log(PARK_CONFIG.securityLevel);
// PARK_CONFIG.unknownField; // Błąd kompilacji!

Od teraz odwołanie do nieistniejącego pola to błąd kompilacji, choć sam obiekt tworzy zupełnie inny skrypt.

Funkcji globalnych

Tak samo opisujesz funkcje z zewnętrznego skryptu, podając samą sygnaturę bez ciała:

// Funkcja zdefiniowana w zewnętrznym skrypcie
declare function initializeFence(
  zone: string,
  voltage: number
): { active: boolean; zone: string };

declare function emergencyShutdown(): void;

// Użycie z type safety
const fence = initializeFence('raptor-paddock', 10000);
console.log(fence.active); // OK
// console.log(fence.power); // Błąd! Nie ma takiej właściwości

Deklaracja mówi, co funkcja przyjmuje i zwraca, a jej kod żyje gdzie indziej.

Klas i namespace

Deklarować można też całe klasy oraz przestrzenie nazw (namespace), które grupują powiązane typy i funkcje, jak w starych bibliotekach ładowanych globalnie:

declare class SecuritySystem {
  constructor(zones: string[]);
  arm(zone: string): void;
  disarm(zone: string): void;
  getStatus(): Record<string, boolean>;
}

declare namespace ParkAPI {
  interface Visitor {
    id: string;
    name: string;
    ticket: 'standard' | 'vip' | 'researcher';
  }

  function registerVisitor(name: string, ticket: Visitor['ticket']): Visitor;
  function getVisitorCount(): number;
}

// Użycie
const system = new SecuritySystem(['zone-a', 'zone-b']);
system.arm('zone-a');

const visitor = ParkAPI.registerVisitor('Alan Grant', 'researcher');
console.log(visitor.ticket);

Wewnątrz declare namespace nie musisz pisać export, bo w kontekście ambient wszystkie składowe są dostępne z zewnątrz.

Pisanie własnych plików deklaracji

Kiedy biblioteka JavaScript nie ma typów, piszesz własny plik .d.ts. Ten opisuje starą bazę dinozaurów. Omit<DinosaurRecord, 'id'> to rekord bez pola id, które nada baza, a Partial<DinosaurRecord> robi wszystkie pola opcjonalnymi:

// plik: types/legacy-dino-db.d.ts
// Opisujemy starą bibliotekę JS do zarządzania bazą dinozaurów

declare module 'legacy-dino-db' {
  export interface DinosaurRecord {
    id: string;
    species: string;
    diet: 'herbivore' | 'carnivore' | 'omnivore';
    weight: number;
    height: number;
    dangerLevel: 1 | 2 | 3 | 4 | 5;
  }

  export interface QueryOptions {
    limit?: number;
    offset?: number;
    sortBy?: keyof DinosaurRecord;
    order?: 'asc' | 'desc';
  }

  export class DinoDB {
    constructor(connectionString: string);
    connect(): Promise<void>;
    disconnect(): Promise<void>;
    findAll(options?: QueryOptions): Promise<DinosaurRecord[]>;
    findById(id: string): Promise<DinosaurRecord | null>;
    insert(record: Omit<DinosaurRecord, 'id'>): Promise<DinosaurRecord>;
    update(id: string, data: Partial<DinosaurRecord>): Promise<DinosaurRecord>;
    delete(id: string): Promise<boolean>;
  }

  // Eksport domyślny
  export default DinoDB;
}

Typy narzędziowe (utility types) składasz jak klocki: zaczynasz od typu bazowego, wybierasz pola przez Pick lub Omit, modyfikujesz je przez Partial lub Required, a na koniec zabezpieczasz przez Readonly. Dane do aktualizacji opisałby więc typ type UpdateDino = Partial<DinosaurRecord>.

DefinitelyTyped i paczki @types

DefinitelyTyped to ogromne repozytorium na GitHubie z plikami deklaracji dla tysięcy bibliotek JavaScript, rozwijane przez społeczność. Każdy zestaw trafia do npm jako @types/nazwa-biblioteki, więc zamiast pisać własne pliki .d.ts, instalujesz gotowe typy:

// Instalacja typów dla popularnych bibliotek:
// npm install --save-dev @types/express
// npm install --save-dev @types/lodash
// npm install --save-dev @types/node

// Po instalacji @types/express możesz pisać:
import express, { Request, Response, NextFunction } from 'express';

const app = express();

// TypeScript zna typy Request, Response, NextFunction
app.get('/dinosaurs/:id', (req: Request, res: Response) => {
  const dinoId: string = req.params.id;
  res.json({ id: dinoId, species: 'T-Rex' });
});

// Bez @types/express - brak informacji o typach!
// req, res byłyby typu "any"

Paczki @types instalujesz jako zależności deweloperskie (--save-dev), bo typy są potrzebne tylko podczas kompilacji.

Jak TypeScript znajduje pliki deklaracji?

Gdy importujesz moduł, TypeScript szuka typów w kilku miejscach, mniej więcej w tej kolejności:

// 1. Typy wbudowane w paczkę (pole "types" w package.json)
// Wiele nowoczesnych bibliotek ma wbudowane .d.ts
// np. axios, zod, prisma

// 2. Paczki @types z node_modules/@types/
// Automatycznie rozpoznawane przez TypeScript
// np. @types/react, @types/node

// 3. Własne pliki .d.ts w projekcie
// Konfiguracja w tsconfig.json:
// {
//   "compilerOptions": {
//     "typeRoots": ["./node_modules/@types", "./types"],
//     "types": ["node", "express"]
//   },
//   "include": ["src/**/*", "types/**/*"]
// }

// 4. Triple-slash directives (rzadko używane)
/// <reference types="node" />
/// <reference path="./custom-types.d.ts" />

Zanim zainstalujesz @types, sprawdź, czy biblioteka nie ma własnych typów. Coraz więcej paczek, na przykład axios czy zod, dostarcza je w środku i wtedy osobna paczka jest zbędna.

Ambient module declarations

Czasami potrzebujesz zadeklarować moduł, który nie jest pakietem npm, na przykład plik CSS, obraz lub JSON. Gwiazdka we wzorcu '*.css' pasuje do każdej ścieżki z tym rozszerzeniem:

// plik: types/assets.d.ts

// Import plików CSS
declare module '*.css' {
  const classes: Record<string, string>;
  export default classes;
}

// Import plików graficznych
declare module '*.png' {
  const src: string;
  export default src;
}

declare module '*.svg' {
  const content: string;
  export default content;
}

// Import plików JSON
declare module '*.json' {
  const value: Record<string, unknown>;
  export default value;
}

// Teraz możesz importować te pliki z type safety:
// import styles from './styles.css';
// import logo from './logo.png';
// import dinoData from './dinosaurs.json';

Deklaracja mówi tylko, co zwróci import, a samo wczytanie pliku zapewnia bundler. Dla JSON-a możesz zamiast niej włączyć opcję resolveJsonModule, która podaje dokładny typ zawartości.

Rozszerzanie istniejących typów (Declaration Merging w .d.ts)

Pliki .d.ts pozwalają też rozszerzać typy z zewnętrznych bibliotek. Dodajemy do żądania Express pola, które ustawia nasz middleware:

// plik: types/express-extension.d.ts
// Rozszerzamy typy Express o dodatkowe pola

import 'express';

// Typ req w handlerach pochodzi z paczki express-serve-static-core
declare module 'express-serve-static-core' {
  interface Request {
    userId?: string;
    parkZone?: string;
    securityClearance?: 'visitor' | 'staff' | 'admin';
  }
}

// Teraz w kodzie aplikacji:
// app.use((req, res, next) => {
//   req.userId = 'USR-001';       // OK - TypeScript zna to pole
//   req.parkZone = 'zone-a';      // OK
//   req.securityClearance = 'staff'; // OK
//   next();
// });

Interfejs Request łączy się z oryginałem (declaration merging), zamiast go zastępować. Rozszerzamy moduł express-serve-static-core, bo stamtąd pochodzi typ req w handlerach, a import 'express' czyni plik modułem, co jest warunkiem rozszerzenia modułu.

Pliki deklaracji (.d.ts) i ekosystem DefinitelyTyped to fundamenty pracy z TypeScript w realnym świecie: dzięki nim korzystasz z tysięcy bibliotek JavaScript z pełnym type safety. Moja kolejność: najpierw typy wbudowane w paczkę, potem @types, a własny plik .d.ts na końcu, zaczynając od funkcji, których naprawdę używasz. W edytorze poniżej przećwiczysz deklaracje, a w kolejnej lekcji poznasz template literal types.

Pamiętaj: plik .d.ts to słownik do starożytnej tablicy, który nie zmienia na niej ani znaku, tylko pozwala ją bezpiecznie odczytać.

Kod do tej lekcji: index.ts
// Declaration files (.d.ts) i DefinitelyTyped
// Park Jurajski - System Deklaracji Typów

// 1. Symulacja: deklarowanie zewnętrznej biblioteki JS
// W prawdziwym projekcie to byłoby w pliku .d.ts

// declare module 'dinosaur-tracker' {
//   export function trackDinosaur(id: string): DinosaurPosition;
// }

// 2. Deklarowanie zmiennych globalnych
// declare const PARK_CONFIG: { name: string; securityLevel: string };

// 3. Symulacja użycia typów z DefinitelyTyped
// Wyobraźmy sobie, że zainstalowaliśmy @types/express

interface DinosaurRecord {
  id: string;
  species: string;
  diet: 'herbivore' | 'carnivore' | 'omnivore';
  weight: number;
  dangerLevel: 1 | 2 | 3 | 4 | 5;
}

interface QueryOptions {
  limit?: number;
  offset?: number;
  sortBy?: keyof DinosaurRecord;
  order?: 'asc' | 'desc';
}

// Symulacja klasy z zewnętrznej biblioteki
class DinoDB {
  private records: DinosaurRecord[] = [
    { id: 'D001', species: 'T-Rex', diet: 'carnivore', weight: 7000, dangerLevel: 5 },
    { id: 'D002', species: 'Triceratops', diet: 'herbivore', weight: 6000, dangerLevel: 2 },
    { id: 'D003', species: 'Velociraptor', diet: 'carnivore', weight: 80, dangerLevel: 4 },
    { id: 'D004', species: 'Brachiosaurus', diet: 'herbivore', weight: 56000, dangerLevel: 1 },
  ];

  findAll(options?: QueryOptions): DinosaurRecord[] {
    let result = [...this.records];
    if (options?.sortBy) {
      result.sort((a, b) => {
        const val = String(a[options.sortBy!]).localeCompare(String(b[options.sortBy!]));
        return options.order === 'desc' ? -val : val;
      });
    }
    const offset = options?.offset || 0;
    const limit = options?.limit || result.length;
    return result.slice(offset, offset + limit);
  }

  findById(id: string): DinosaurRecord | null {
    return this.records.find(r => r.id === id) || null;
  }
}

// 4. Rozszerzanie typów (Declaration Merging)
// W prawdziwym projekcie rozszerzamy np. Express.Request

interface ParkRequest {
  userId?: string;
  parkZone?: string;
  securityClearance?: 'visitor' | 'staff' | 'admin';
}

// Test
const db = new DinoDB();

console.log("=== Baza dinozaurów (symulacja @types) ===");
console.log("\nWszystkie rekordy:");
db.findAll().forEach(d =>
  console.log(`  ${d.species} (diet: ${d.diet}, danger: ${d.dangerLevel})`)
);

console.log("\nPosortowane po wadze (desc), limit 2:");
db.findAll({ sortBy: 'weight', order: 'desc', limit: 2 }).forEach(d =>
  console.log(`  ${d.species}: ${d.weight}kg`)
);

console.log("\nSzukam T-Rex:");
const trex = db.findById('D001');
if (trex) {
  console.log(`  Znaleziono: ${trex.species}, danger level: ${trex.dangerLevel}`);
}

// 5. Ambient declarations - typy dla zasobów
// declare module '*.css' { const classes: Record<string, string>; export default classes; }
// declare module '*.png' { const src: string; export default src; }

console.log("\n=== Typy deklaracji (.d.ts) ===");
console.log("• declare module - deklaracja modułu zewnętrznego");
console.log("• declare const/function - globalne zmienne/funkcje");
console.log("• @types/xxx - gotowe typy z DefinitelyTyped");
console.log("• *.d.ts - pliki z samymi typami, bez implementacji");

Hasła z dokumentacji w tej lekcji

Widzisz błąd w tej lekcji?

Sprawdź się

Odpowiedz na pytania z tej lekcji. Wybierz odpowiedź, a od razu zobaczysz, czy jest poprawna.

  1. 1. Co zawierają pliki z rozszerzeniem .d.ts w TypeScript?

  2. 2. Czym jest repozytorium DefinitelyTyped i paczki @types?

Zadania praktyczne w grze

  • Edytor kodu

    Napisz deklaracje typów dla zewnętrznej biblioteki i zmiennych globalnych używając declare.

  • Klikanie w kolejności

    Ułóż elementy deklaracji modułu zewnętrznego w TypeScript:

  • Edytor kodu

    Stwórz deklaracje typów dla modułu dinosaur-tracker używając declare module.

  • Układanie w poziomie

    Ułóż elementy deklaracji typu Partial w odpowiedniej kolejności:

  • Układanie w pionie

    Ułóż kroki budowania złożonego typu narzędziowego:

  1. PytaniePliki deklaracji .d.ts
  2. PytanieDefinitelyTyped i paczki @types
  3. Zadanie z kodemĆwiczenie: Słowo kluczowe declare
  4. Kliknij w kolejnościDeklaracja modułu zewnętrznego
  5. Zadanie z kodemĆwiczenie: Plik deklaracji dla biblioteki
  6. Ułóż w kolejnościPowtórzenie: Kolejność: Partial type
  7. Ułóż w kolejnościPowtórzenie: Budowanie złożonego utility type

Przydatne artykuły