Kurs JavaScript i TypeScript · Moduł 10: TypeScript w praktyce
Declaration files (.d.ts) i DefinitelyTyped
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ściDeklaracja 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. Co zawierają pliki z rozszerzeniem .d.ts w TypeScript?
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:
Zadania po tej lekcji
- PytaniePliki deklaracji .d.ts
- PytanieDefinitelyTyped i paczki @types
- Zadanie z kodemĆwiczenie: Słowo kluczowe declare
- Kliknij w kolejnościDeklaracja modułu zewnętrznego
- Zadanie z kodemĆwiczenie: Plik deklaracji dla biblioteki
- Ułóż w kolejnościPowtórzenie: Kolejność: Partial type
- Ułóż w kolejnościPowtórzenie: Budowanie złożonego utility type