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

Type-safe Event System w TypeScript

8 min czytania ·
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. 1. Czym jest EventMap w kontekście type-safe event systemu?

  2. 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:

  1. PytanieEventMap w TypeScript
  2. PytanieGeneryczny EventEmitter
  3. Zadanie z kodemĆwiczenie: Typowany emitter zdarzeń
  4. Zadanie z kodemĆwiczenie: EventMap i handlery zdarzeń
  5. Ułóż w kolejnościSkładnia metody emit w TypedEventEmitter
  6. Ułóż w kolejnościPowtórzenie: Ewaluacja conditional type
  7. Ułóż w kolejnościPowtórzenie: Składnia infer

Przydatne artykuły