SignalManager: improve type safety and reduce boilerplate

[williamsyang-work]

⚠️ IMPORTANT: Dependency Warning ⚠️

This PR introduces type changes that will affect the vscode-trace-extension repository.
DO NOT MERGE until maintainers have reviewed and approved the proposed changes.
A corresponding PR will need to be created in vscode-trace-extension to handle these type updates.

👉 Maintainers: Please review and comment on the proposed type system before work begins on the extension repository.

Improve SignalManager Type Safety and Developer Experience

Overview

This PR refactors the SignalManager to provide better TypeScript support and improved developer experience. The changes focus on making the event system more type-safe while reducing boilerplate code.

Key Improvements

💡 Better Type Inference

// Before - No type inference on payload
signalManager.on('THEME_CHANGED', (theme) => {
    console.log(theme.toUpperCase()); // TS doesn't know theme is a string
});

// After - Full type inference
signalManager.on('THEME_CHANGED', (theme) => {
    console.log(theme.toUpperCase()); // TS knows theme is a string
});

🛡️ Compile-Time Type Safety

// Before - TypeScript wouldn't catch this error
signalManager.emit('THEME_CHANGED', 123); // Should be string

// After - TypeScript catches invalid payload types
signalManager.emit('THEME_CHANGED', 123); // Type error!

📝 Better IDE Support

• Autocomplete for event names
• Parameter type hints for event handlers
• Inline documentation for all methods

🧹 Reduced Boilerplate

// Before - Required separate fire* method for each event
class SignalManager {
    fireThemeChangedSignal(theme: string): void {
        this.emit(Signals.THEME_CHANGED, theme);
    }
    fireTraceOpenedSignal(trace: Trace): void {
        this.emit(Signals.TRACE_OPENED, trace);
    }
    // ... many more fire* methods
}

// After - Direct emit with type safety
signalManager.emit('THEME_CHANGED', theme);
signalManager.emit('TRACE_OPENED', trace);

Implementation Details

• Consolidated signal types into a single Signals interface
• Added generic type constraints for event handlers
• Enhanced JSDoc documentation for core methods
• Maintained backward compatibility with existing event system

[bhufmann]

Thanks for the proposal. It looks like a simplification. I had a first glance over the changes and have a general comment using Strings. Please have look.

[bhufmann]

I think that a String has to be passed manually instead of a String constant as before (Signals.THEME_CHANGED) is more error-prone, because it's not caught at build time. Think we should have something similar as before.

[bhufmann]

I think that a String has to be passed manually instead of a String constant as before (Signals.THEME_CHANGED) is more error-prone, because it's not caught at build time. Think we should have something similar as before.

[williamsyang-work]

The current setup is actually type-safe! The SignalType = keyof Signals type means TypeScript will only accept exact string matches of the events defined in our Signals interface. You can't pass an arbitrary string - TypeScript will catch any typos or invalid events at compile time:

signalManager.on('THEME_CHANGED', ...) // ✅ Works fine
signalManager.on('INVALID_EVENT', ...) // ❌ Compile error
signalManager.on('theme_changed', ...) // ❌ Compile error

Plus, we get the bonus of TypeScript automatically inferring the correct parameter types for our listeners. So we're getting all the safety of constants with better ergonomics.

Here's a screengrab of how this looks in vscode:

Screencast.from.10-25-2024.09.55.57.AM.webm

[bhufmann]

I think that a String has to be passed manually instead of a String constant as before (Signals.THEME_CHANGED) is more error-prone, because it's not caught at build time. Think we should have something similar as before.