Type-Safe Event Management with TypeScript Enums

Our event system used string literals for event names, causing typos, missing events, and no type safety. Replacing magic strings with TypeScript enums and a typed event emitter eliminated all event-related bugs and improved IDE autocomplete.

// String literals - no type safety!
eventBus.emit('annotation:created', data);
eventBus.on('annotatoin:created', handler);  // Typo! Silent failure

// No way to know what events exist
eventBus.emit('some-random-event', data);  // Valid but wrong

// No payload type checking
eventBus.on('annotation:created', (data: any) => {
  // data could be anything!
});

Issues: Typos cause silent failures, no autocomplete, no type checking, debugging is nightmare.

// events/types.ts
export enum CanvasEvent {
  ANNOTATION_CREATED = 'annotation:created',
  ANNOTATION_UPDATED = 'annotation:updated',
  ANNOTATION_DELETED = 'annotation:deleted',
  TOOL_CHANGED = 'tool:changed',
  ZOOM_CHANGED = 'zoom:changed',
}

// Define payload types for each event
export interface CanvasEventPayloads {
  [CanvasEvent.ANNOTATION_CREATED]: { id: string; annotation: Annotation };
  [CanvasEvent.ANNOTATION_UPDATED]: { id: string; changes: Partial<Annotation> };
  [CanvasEvent.ANNOTATION_DELETED]: { id: string };
  [CanvasEvent.TOOL_CHANGED]: { tool: ToolType; previous: ToolType };
  [CanvasEvent.ZOOM_CHANGED]: { zoom: number; previous: number };
}

// Type-safe event emitter
class TypedEventEmitter<Events extends Record<string, any>> {
  private listeners = new Map<keyof Events, Set<Function>>();

  on<K extends keyof Events>(
    event: K,
    handler: (payload: Events[K]) => void
  ): () => void {
    if (!this.listeners.has(event)) {
      this.listeners.set(event, new Set());
    }

    this.listeners.get(event)!.add(handler);

    // Return unsubscribe function
    return () => this.off(event, handler);
  }

  off<K extends keyof Events>(
    event: K,
    handler: (payload: Events[K]) => void
  ): void {
    this.listeners.get(event)?.delete(handler);
  }

  emit<K extends keyof Events>(event: K, payload: Events[K]): void {
    const handlers = this.listeners.get(event);

    if (handlers) {
      handlers.forEach(handler => handler(payload));
    }
  }

  once<K extends keyof Events>(
    event: K,
    handler: (payload: Events[K]) => void
  ): void {
    const onceHandler = (payload: Events[K]) => {
      handler(payload);
      this.off(event, onceHandler);
    };

    this.on(event, onceHandler);
  }
}

// Create typed event bus
export const canvasEvents = new TypedEventEmitter<CanvasEventPayloads>();

// Usage - fully type-safe!
canvasEvents.emit(CanvasEvent.ANNOTATION_CREATED, {
  id: '123',
  annotation: newAnnotation  // ✓ Type checked!
});

canvasEvents.on(CanvasEvent.ANNOTATION_CREATED, (payload) => {
  // payload is typed as { id: string; annotation: Annotation }
  console.log(payload.annotation.id);  // ✓ Autocomplete works!
});

// Typos caught at compile time!
canvasEvents.emit('annotatoin:created', data);  // ✗ Compile error!

React hook integration:

function useCanvasEvent<K extends keyof CanvasEventPayloads>(
  event: K,
  handler: (payload: CanvasEventPayloads[K]) => void
) {
  useEffect(() => {
    const unsubscribe = canvasEvents.on(event, handler);
    return unsubscribe;  // Cleanup on unmount
  }, [event, handler]);
}

// Usage in component
function AnnotationPanel() {
  useCanvasEvent(CanvasEvent.ANNOTATION_CREATED, (payload) => {
    console.log('New annotation:', payload.annotation);
    // payload is fully typed!
  });
}

1. Enums for Event Names: Prevent typos and enable autocomplete
2. Type Event Payloads: Know exactly what data each event carries
3. Generic Event Emitter: Reusable pattern for all events
4. React Hook Wrapper: Automatic cleanup in components
5. Compile-Time Safety: Catch errors before runtime