Kurs JavaScript i TypeScript · Moduł 10: TypeScript w praktyce
Type-safe Event System w TypeScript
W tej lekcji5
W Parku Jurajskim każdy system musi natychmiast reagować na zdarzenia: alarm o ucieczce raptorów, zmianę stanu ogrodzenia, nową pozycję dinozaura. Taki system zdarzeń (event system) wymaga precyzji, bo nie możesz wysłać danych o temperaturze do handlera, który czeka na współrzędne GPS. Zwykły emiter przyjmuje dowolny napis i dowolne dane, więc literówka w nazwie zdarzenia po cichu gubi alarm. TypeScript pozwala stworzyć w pełni typowany system eventów, w którym kompilator pilnuje poprawności za Ciebie.
EventMap - mapa typów zdarzeń
Fundamentem type-safe event systemu jest EventMap: interfejs mapujący nazwy zdarzeń na typy ich danych (payload). Nazwy w stylu dinosaur:escaped to zwykłe klucze napisowe, a dwukropek porządkuje je w grupy:
// Definiujemy mapę zdarzeń parku
interface ParkEventMap {
'dinosaur:escaped': { species: string; paddock: string; dangerLevel: number };
'fence:status': { zone: string; voltage: number; active: boolean };
'visitor:enter': { visitorId: string; gate: string; timestamp: Date };
'visitor:exit': { visitorId: string; gate: string; timestamp: Date };
'alert:weather': { type: 'storm' | 'heat' | 'flood'; severity: 1 | 2 | 3 };
}
// TypeScript zna dokładny kształt danych dla każdego zdarzenia
// 'dinosaur:escaped' => { species: string; paddock: string; dangerLevel: number }
// 'fence:status' => { zone: string; voltage: number; active: boolean }Sam interfejs nie generuje żadnego kodu. To umowa, z której skorzystają wszystkie metody emitera.
Generic EventEmitter z TypeScript
Teraz generyczny emiter. Parametr T to mapa zdarzeń, a każda metoda ma własny parametr K extends keyof T, czyli nazwę jednego zdarzenia, więc T[K] oznacza dokładnie payload tego zdarzenia:
// Generyczny EventEmitter - T to mapa eventów
class TypedEventEmitter<T extends Record<string, any>> {
private listeners: {
[K in keyof T]?: Array<(data: T[K]) => void>;
} = {};
on<K extends keyof T>(event: K, handler: (data: T[K]) => void): void {
if (!this.listeners[event]) {
this.listeners[event] = [];
}
this.listeners[event]!.push(handler);
}
off<K extends keyof T>(event: K, handler: (data: T[K]) => void): void {
const handlers = this.listeners[event];
if (handlers) {
const index = handlers.indexOf(handler);
if (index > -1) handlers.splice(index, 1);
}
}
emit<K extends keyof T>(event: K, data: T[K]): void {
const handlers = this.listeners[event];
if (handlers) {
[...handlers].forEach(handler => handler(data)); // kopia: once() usuwa handler w trakcie pętli
}
}
once<K extends keyof T>(event: K, handler: (data: T[K]) => void): void {
const wrapper = (data: T[K]) => {
handler(data);
this.off(event, wrapper);
};
this.on(event, wrapper);
}
}emit przechodzi po kopii tablicy handlerów, bo once usuwa swój wrapper w trakcie pętli, a na oryginale kolejny handler zostałby pominięty. Klasa nie zna żadnych konkretnych zdarzeń, wszystko wyczytuje z mapy. Wykrzyknik w this.listeners[event]! to asercja non-null: mówisz kompilatorowi, że tablica na pewno istnieje, bo linijkę wyżej ją utworzyłeś.
Podłączamy mapę parku. Parametr data w handlerze nie wymaga adnotacji, bo TypeScript wyprowadza jego typ z nazwy zdarzenia:
// Użycie z ParkEventMap
const parkEvents = new TypedEventEmitter<ParkEventMap>();
// TypeScript zna typ parametru handler - auto-complete działa!
parkEvents.on('dinosaur:escaped', (data) => {
// data jest typu { species: string; paddock: string; dangerLevel: number }
console.log(`ALARM! ${data.species} uciekł z ${data.paddock}!`);
console.log(`Poziom zagrożenia: ${data.dangerLevel}`);
});
parkEvents.on('fence:status', (data) => {
// data jest typu { zone: string; voltage: number; active: boolean }
if (!data.active) {
console.log(`Ogrodzenie w strefie ${data.zone} wyłączone!`);
}
});W pierwszym handlerze podpowiedzi pokażą species, paddock i dangerLevel, a w drugim zupełnie inne pola.
Wywołanie emit przyjmuje nazwę zdarzenia i pasujący do niej obiekt. Zobacz, co kompilator robi z błędnymi wywołaniami:
// Poprawne emisje
parkEvents.emit('dinosaur:escaped', {
species: 'Velociraptor',
paddock: 'B-7',
dangerLevel: 5
});
// Błąd kompilacji! Brakuje pola 'dangerLevel'
// parkEvents.emit('dinosaur:escaped', { species: 'T-Rex', paddock: 'A-1' });
// Błąd kompilacji! Nieznane zdarzenie
// parkEvents.emit('dinosaur:sleeping', { species: 'Stegosaurus' });Brakujące pole i nieznana nazwa zdarzenia to błędy kompilacji, a nie ciche awarie w działającym parku. To główna przewaga nad nietypowanym emiterem.
Pattern: Strongly-typed addEventListener
W definicjach typów DOM w TypeScripcie addEventListener jest typowany właśnie dzięki mapom zdarzeń, takim jak HTMLElementEventMap. Zbudujmy własną wersję tego wzorca, zaczynając od mapy i klasy bazowej:
// Mapa eventów dla komponentu UI
interface UIEventMap {
click: { x: number; y: number; target: string };
hover: { x: number; y: number; element: string };
keypress: { key: string; code: number; ctrl: boolean; shift: boolean };
resize: { width: number; height: number };
scroll: { scrollTop: number; scrollLeft: number };
}
// Klasa komponentu z typowanymi eventami
class UIComponent<Events extends Record<string, any> = UIEventMap> {
private eventHandlers: Map<keyof Events, Set<Function>> = new Map();
addEventListener<K extends keyof Events>(
type: K,
listener: (event: Events[K]) => void
): void {
if (!this.eventHandlers.has(type)) {
this.eventHandlers.set(type, new Set());
}
this.eventHandlers.get(type)!.add(listener);
}
removeEventListener<K extends keyof Events>(
type: K,
listener: (event: Events[K]) => void
): void {
this.eventHandlers.get(type)?.delete(listener);
}
protected dispatchEvent<K extends keyof Events>(
type: K,
event: Events[K]
): void {
this.eventHandlers.get(type)?.forEach(handler => {
(handler as (event: Events[K]) => void)(event);
});
}
}Domyślny parametr = UIEventMap sprawia, że zwykły komponent od razu zna podstawowe zdarzenia, a dispatchEvent jest protected, więc zdarzenia wysyła tylko sam komponent.
Mapa rozszerzona przez extends dodaje zdarzenia mapy parku, a klasa pochodna przekazuje ją jako parametr typu:
// Rozszerzony komponent z własnymi eventami
interface MapComponentEvents extends UIEventMap {
'marker:click': { markerId: string; lat: number; lng: number };
'zone:select': { zoneId: string; name: string };
}
class ParkMapComponent extends UIComponent<MapComponentEvents> {
selectZone(zoneId: string, name: string): void {
this.dispatchEvent('zone:select', { zoneId, name });
}
clickMarker(markerId: string, lat: number, lng: number): void {
this.dispatchEvent('marker:click', { markerId, lat, lng });
}
}
// Użycie
const parkMap = new ParkMapComponent();
parkMap.addEventListener('marker:click', (event) => {
// event: { markerId: string; lat: number; lng: number }
console.log(`Kliknięto marker ${event.markerId} na ${event.lat}, ${event.lng}`);
});
parkMap.addEventListener('click', (event) => {
// event: { x: number; y: number; target: string }
console.log(`Kliknięto na ${event.x}, ${event.y}`);
});parkMap zna zarówno własne zdarzenia (marker:click), jak i odziedziczone (click), a każdy handler dostaje właściwy typ.
Middleware pattern z typowanymi eventami
Zaawansowany wzorzec to middleware, który przetwarza zdarzenie przed dotarciem do handlera, jak śluza przed wybiegiem. reduceRight składa łańcuch od końca, więc middleware wykonują się w kolejności rejestracji:
// Typ middleware - przetwarza event i decyduje czy go przepuścić
type EventMiddleware<T> = (
data: T,
next: (data: T) => void
) => void;
class MiddlewareEventEmitter<T extends Record<string, any>> {
private listeners: { [K in keyof T]?: Array<(data: T[K]) => void> } = {};
private middleware: { [K in keyof T]?: Array<EventMiddleware<T[K]>> } = {};
on<K extends keyof T>(event: K, handler: (data: T[K]) => void): void {
if (!this.listeners[event]) this.listeners[event] = [];
this.listeners[event]!.push(handler);
}
use<K extends keyof T>(event: K, mw: EventMiddleware<T[K]>): void {
if (!this.middleware[event]) this.middleware[event] = [];
this.middleware[event]!.push(mw);
}
emit<K extends keyof T>(event: K, data: T[K]): void {
const mws = this.middleware[event] || [];
const handlers = this.listeners[event] || [];
// Budujemy łańcuch middleware
const chain = mws.reduceRight(
(next: (data: T[K]) => void, mw: EventMiddleware<T[K]>) => {
return (d: T[K]) => mw(d, next);
},
(finalData: T[K]) => {
handlers.forEach(h => h(finalData));
}
);
chain(data);
}
}
// Przykład: logowanie i walidacja eventów
const securitySystem = new MiddlewareEventEmitter<ParkEventMap>();
// Middleware logujący
securitySystem.use('dinosaur:escaped', (data, next) => {
console.log(`[LOG] Zdarzenie ucieczki: ${data.species}`);
next(data);
});
// Middleware eskalujący poziom zagrożenia
securitySystem.use('dinosaur:escaped', (data, next) => {
if (data.species === 'T-Rex' && data.dangerLevel < 5) {
next({ ...data, dangerLevel: 5 }); // Eskalacja!
} else {
next(data);
}
});
securitySystem.on('dinosaur:escaped', (data) => {
console.log(`Finalny alert: ${data.species}, zagrożenie: ${data.dangerLevel}`);
});
securitySystem.emit('dinosaur:escaped', {
species: 'T-Rex',
paddock: 'A-1',
dangerLevel: 3 // Zostanie eskalowany do 5 przez middleware
});Drugi middleware podnosi poziom zagrożenia T-Rexa do 5, zanim zobaczy go handler, a pierwotny obiekt zostaje nietknięty dzięki spreadowi.
Wyciąganie typów zdarzeń (utility types dla eventów)
Na koniec typy pomocnicze. EventsWithField łączy typ mapowany z typem warunkowym: zapis A extends B ? X : Y działa jak if w świecie typów, czyli sprawdza typ wejściowy, ocenia warunek extends i zwraca X albo Y:
// Utility types do pracy z event mapami
type EventNames<T> = keyof T & string;
type EventPayload<T, K extends keyof T> = T[K];
type EventHandler<T, K extends keyof T> = (data: T[K]) => void;
// Wyciągnięcie handlera dla konkretnego eventu
type ParkEscapeHandler = EventHandler<ParkEventMap, 'dinosaur:escaped'>;
// (data: { species: string; paddock: string; dangerLevel: number }) => void
// Typ unii wszystkich payloadów
type AnyParkPayload = ParkEventMap[keyof ParkEventMap];
// Filtrowanie eventów po typie payloadu
type EventsWithField<T, Field extends string> = {
[K in keyof T]: Field extends keyof T[K] ? K : never;
}[keyof T];
type EventsWithVisitorId = EventsWithField<ParkEventMap, 'visitorId'>;
// 'visitor:enter' | 'visitor:exit'Typ warunkowy możesz połączyć z infer, żeby wyciągnąć fragment typu, na przykład type Return<T> = T extends (...args: any) => infer R ? R : never zwraca typ wyniku funkcji.
Type-safe event system to wzorzec, który sprawdza się wszędzie: od systemów monitoringu w Parku Jurajskim po frontend React, backendy Node.js i mikroserwisy. Generyczny TypedEventEmitter z EventMap daje pełne type safety, bo kompilator pilnuje, że emitujesz i nasłuchujesz dokładnie tych danych, które zadeklarowałeś. Polecam trzymać mapę zdarzeń w jednym pliku: to najlepsza dokumentacja komunikacji w systemie. W edytorze poniżej zbudujesz system monitoringu zdarzeń, a w kolejnej lekcji przeniesiesz TypeScript na serwer z Node.js.
Pamiętaj: mapa zdarzeń to rozkład częstotliwości radia parku, dzięki któremu każdy strażnik słyszy tylko komunikaty w formacie, którego się spodziewa.
Kod do tej lekcji: index.ts
// Type-safe Event System w TypeScript
// Park Jurajski - System Monitoringu Zdarzeń
// 1. EventMap - mapa typów zdarzeń
interface ParkEventMap {
'dinosaur:escaped': { species: string; paddock: string; dangerLevel: number };
'fence:status': { zone: string; voltage: number; active: boolean };
'visitor:enter': { visitorId: string; gate: string };
'alert:weather': { type: 'storm' | 'heat' | 'flood'; severity: 1 | 2 | 3 };
}
// 2. Generyczny TypedEventEmitter
class TypedEventEmitter<T extends Record<string, any>> {
private listeners: { [K in keyof T]?: Array<(data: T[K]) => void> } = {};
on<K extends keyof T>(event: K, handler: (data: T[K]) => void): void {
if (!this.listeners[event]) {
this.listeners[event] = [];
}
this.listeners[event]!.push(handler);
}
off<K extends keyof T>(event: K, handler: (data: T[K]) => void): void {
const handlers = this.listeners[event];
if (handlers) {
const idx = handlers.indexOf(handler);
if (idx > -1) handlers.splice(idx, 1);
}
}
emit<K extends keyof T>(event: K, data: T[K]): void {
const handlers = this.listeners[event];
if (handlers) {
handlers.forEach(h => h(data));
}
}
once<K extends keyof T>(event: K, handler: (data: T[K]) => void): void {
const wrapper = (data: T[K]) => {
handler(data);
this.off(event, wrapper);
};
this.on(event, wrapper);
}
}
// 3. Utility types dla eventów
type EventNames<T> = keyof T & string;
type EventPayload<T, K extends keyof T> = T[K];
type EventHandler<T, K extends keyof T> = (data: T[K]) => void;
// 4. Test systemu
const parkEvents = new TypedEventEmitter<ParkEventMap>();
// Rejestracja handlerów z pełnym type safety
parkEvents.on('dinosaur:escaped', (data) => {
// TypeScript wie: data = { species, paddock, dangerLevel }
console.log(`ALARM! ${data.species} uciekł z ${data.paddock}!`);
console.log(` Poziom zagrożenia: ${data.dangerLevel}/5`);
});
parkEvents.on('fence:status', (data) => {
const status = data.active ? 'AKTYWNE' : 'WYŁĄCZONE';
console.log(`Ogrodzenie ${data.zone}: ${status} (${data.voltage}V)`);
});
parkEvents.on('visitor:enter', (data) => {
console.log(`Gość ${data.visitorId} wszedł bramą ${data.gate}`);
});
parkEvents.once('alert:weather', (data) => {
console.log(`Alert pogodowy (once): ${data.type}, stopień ${data.severity}`);
});
// Emisja zdarzeń
console.log("=== Park Jurajski Event System ===\n");
parkEvents.emit('visitor:enter', {
visitorId: 'VIS-042',
gate: 'Główna'
});
parkEvents.emit('fence:status', {
zone: 'Raptor Paddock',
voltage: 15000,
active: true
});
parkEvents.emit('dinosaur:escaped', {
species: 'Velociraptor',
paddock: 'B-7',
dangerLevel: 4
});
parkEvents.emit('alert:weather', {
type: 'storm',
severity: 2
});
// Drugi alert nie wywoła handlera (once!)
parkEvents.emit('alert:weather', {
type: 'heat',
severity: 1
});
console.log("\n--- Drugi alert pogodowy nie został obsłużony (once) ---");
// Poniższe NIE skompilowałoby się w TypeScript:
// parkEvents.emit('dinosaur:escaped', { species: 'T-Rex' }); // Brak paddock i dangerLevel!
// parkEvents.emit('unknown:event', {}); // Nieznane zdarzenie!
console.log("\n=== Type-safe events działają! ===");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. Czym jest EventMap w kontekście type-safe event systemu?
2. Jaką zaletę daje generyczny TypedEventEmitter<T> w porównaniu z nietypowanym emitterem?
Zadania praktyczne w grze
- Edytor kodu
Zaimplementuj generyczny TypedEventEmitter z metodami on, emit i off.
- Edytor kodu
Stwórz EventMap z typowanymi payloadami i zarejestruj handlery.
- Układanie w poziomie
Ułóż elementy wywołania emit w typowanym emitterze:
- Układanie w pionie
Ułóż kroki ewaluacji conditional type T extends U ? X : Y:
- Układanie w poziomie
Ułóż elementy conditional type z infer:
Zadania po tej lekcji
- PytanieEventMap w TypeScript
- PytanieGeneryczny EventEmitter
- Zadanie z kodemĆwiczenie: Typowany emitter zdarzeń
- Zadanie z kodemĆwiczenie: EventMap i handlery zdarzeń
- Ułóż w kolejnościSkładnia metody emit w TypedEventEmitter
- Ułóż w kolejnościPowtórzenie: Ewaluacja conditional type
- Ułóż w kolejnościPowtórzenie: Składnia infer