Forem: Ryan

VSCode 4 - Command and Keybinding

Ryan — Sun, 13 Apr 2025 12:29:49 +0000

When you press Ctrl+S to save a file, or use the Command Palette to run a Git command, you're interacting with VSCode's Commands and Keybindings system.

In this article, we'll explore how VSCode manages commands and keyboard shortcuts through a well-designed system that enables both core functionality and extension capabilities.

The Problem: Managing Editor Commands

Every code editor needs to handle commands - discrete actions that users can trigger through various means:

Saving a file (Ctrl+S)
Opening the command palette (Ctrl+Shift+P)
Running a build task

In traditional editors, Saving commands might be implemented directly:

// Traditional approach
document.addEventListener('keydown', (e) => {
  // Handle Ctrl+S to save
  if (e.ctrlKey && e.key === 's') {
    saveCurrentFile();
    e.preventDefault();
  }
  // Many more keyboard shortcuts...
});

// Menu click handlers
saveButton.addEventListener('click', () => {
  saveCurrentFile();
});

// Different implementations for the same action
function saveCurrentFile() {
  // Logic to save the current file
}

This approach becomes problematic as the editor grows:

The same action has multiple implementations (keyboard handler, menu handler, etc.)
Keyboard shortcuts are hardcoded and not customizable
Extensions can't easily add new commands or override existing ones
Command logic is scattered throughout the codebase

VSCode needed a better solution - a unified way to define, register, and execute commands, regardless of how they're triggered.

VSCode's Solution: The Command + Keybinding Architecture

VSCode solves these challenges through a layered architecture with four key components:

CommandsRegistry: Stores all command definitions
CommandService: Handles command execution
KeybindingsRegistry: Stores mappings from key to commands
KeybindingService: Captures keyboard input and triggers the right commands

Visualizing the Flow

┌─────────────────────────────────────────────────┐
│               KeybindingService                 │
│                                                 │
│  1. Receives keyboard event                     │
│  2. Converts to VSCode key code                 │
│  3. Finds matching keybinding                   │
└───────────────────────┬─────────────────────────┘
                        │
                        │ Uses
                        ▼
┌─────────────────────────────────────────────────┐
│               KeybindingsRegistry               │
│                                                 │
│  Stores keybinding rules mapping:               │
│  - Key combinations to command IDs              │
└───────────────────────┬─────────────────────────┘
                        │
                        │ Provides command ID
                        ▼
┌─────────────────────────────────────────────────┐
│                CommandService                   │
│                                                 │
│  1. Takes command ID                            │
│  2. Looks up command handler                    │
│  3. Creates DI accessor                         │
│  4. Executes handler with accessor and args     │
└───────────────────────┬─────────────────────────┘
                        │
                        │ Uses
                        ▼
┌─────────────────────────────────────────────────┐
│               CommandsRegistry                  │
│                                                 │
│  Stores command definitions:                    │
│  - Command ID → Command handler                 │
└─────────────────────────────────────────────────┘

Let's deep into each component in detail.

CommandsRegistry: The Command Store

At its core, the CommandsRegistry is a simple map from command IDs to handler functions.

// Type definitions that describe command structure
export type ICommandsMap = Map<string, ICommand>;

export interface ICommandHandler {
  (accessor: ServicesAccessor, ...args: any[]): void;
}

export interface ICommand {
  id: string;
  handler: ICommandHandler;
  metadata?: ICommandMetadata | null;
}

Each command has:

A unique string ID (like 'editor.action.formatDocument')
A handler function that defines what happens when the command runs

The handler function's type is ICommandHandle which receives two important things:

An accessor to VSCode's services (for dependency injection)
Any arguments passed to the command

export const CommandsRegistry: ICommandRegistry = new class implements ICommandRegistry {
  private readonly _commands = new Map<string, LinkedList<ICommand>>();

  private readonly _onDidRegisterCommand = new Emitter<string>();
  readonly onDidRegisterCommand: Event<string> = this._onDidRegisterCommand.event;

  registerCommand(idOrCommand: string | ICommand, handler?: ICommandHandler): IDisposable {
    if (!idOrCommand) throw new Error(`invalid command`);

    if (typeof idOrCommand === 'string') {
      if (!handler) throw new Error(`invalid command`);
      return this.registerCommand({ id: idOrCommand, handler });
    }

    // ...argument validation if have metadata.args

    // Set command
    const { id } = idOrCommand;
    let commands = this._commands.get(id);
    if (!commands) {
      commands = new LinkedList<ICommand>();
      this._commands.set(id, commands);
    }

    // Remove command in dispose
    const removeFn = commands.unshift(idOrCommand);
    const ret = toDisposable(() => {
      removeFn();
      const command = this._commands.get(id);
      if (command?.isEmpty()) {
        this._commands.delete(id);
      }
    });

    // Tell the world about this command 
    this._onDidRegisterCommand.fire(id);

    return markAsSingleton(ret);
  }

  getCommand(id: string): ICommand | undefined {
    const list = this._commands.get(id);
    if (!list || list.isEmpty()) {
      return undefined;
    }
    return Iterable.first(list);
  }
};

// Example usage
CommandsRegistry.registerCommand('myExtension.sayHello', (accessor, name: string) => {
  const notificationService = accessor.get(INotificationService);
  notificationService.info(`Hello, ${name}!`);
});

CommandService: The Command Executor

When it's time to run a command, the CommandService takes over.

export class StandaloneCommandService implements ICommandService {
  declare readonly _serviceBrand: undefined;

  private readonly _instantiationService: IInstantiationService;

  private readonly _onWillExecuteCommand = new Emitter<ICommandEvent>();
  private readonly _onDidExecuteCommand = new Emitter<ICommandEvent>();
  public readonly onWillExecuteCommand: Event<ICommandEvent> = this._onWillExecuteCommand.event;
  public readonly onDidExecuteCommand: Event<ICommandEvent> = this._onDidExecuteCommand.event;

  constructor(
    @IInstantiationService instantiationService: IInstantiationService
  ) {
    this._instantiationService = instantiationService;
  }

  public executeCommand<T>(id: string, ...args: any[]): Promise<T> {
    const command = CommandsRegistry.getCommand(id);
    if (!command) {
      return Promise.reject(new Error(`command '${id}' not found`));
    }

    try {
      this._onWillExecuteCommand.fire({ commandId: id, args });
      const result = this._instantiationService.invokeFunction.apply(this._instantiationService, [command.handler, ...args]) as T;

      this._onDidExecuteCommand.fire({ commandId: id, args });
      return Promise.resolve(result);
    } catch (err) {
      return Promise.reject(err);
    }
  }
}

The CommandService:

Looks up the command handler in the registry
Send the handle and args to invokeFunction
Executes the handler and call other services in handle with access.get
Returns a Promise with the result

This design makes command execution consistent, regardless of what triggered it.

KeybindingsRegistry: Mapping Keys to Commands

The KeybindingsRegistry stores mappings from keyboard shortcuts to command IDs.

// Type definitions that describe keybinding structure
export interface IKeybindings {
  primary?: number;            // Main keybinding (bit flags representing key combination)
  secondary?: number[];        // Alternative keybindings
  win?: {                      // Windows-specific
    primary: number;
    secondary?: number[];
  };
  linux?: {                    // Linux-specific
    primary: number;
    secondary?: number[];
  };
  mac?: {                      // macOS-specific
    primary: number;
    secondary?: number[];
  };
}

export interface IKeybindingRule extends IKeybindings {
  id: string;                  // Command identifier
  weight: number;              // Determines precedence when multiple bindings match
  args?: any;                  // Optional arguments to pass to the command
  when?: ContextKeyExpression | null | undefined;  // Context condition when binding applies
}

// Implementation of the KeybindingsRegistry
class KeybindingsRegistryImpl implements IKeybindingsRegistry {
  private _coreKeybindings: LinkedList<IKeybindingItem>;

  constructor() {
    this._coreKeybindings = new LinkedList();
  }

  // Registers a keybinding rule and returns a disposable to unregister it
  public registerKeybindingRule(rule: IKeybindingRule): IDisposable {
    // Convert platform-agnostic rule to the current platform's equivalent
    const actualKb = KeybindingsRegistryImpl.bindToCurrentPlatform(rule);
    const result = new DisposableStore();

    // Register primary keybinding if it exists
    if (actualKb && actualKb.primary) {
      const kk = decodeKeybinding(actualKb.primary, OS);  // Convert to internal representation
      if (kk) {
        result.add(this._registerDefaultKeybinding(kk, rule.id, rule.args, rule.weight, 0, rule.when));
      }
    }

    // Register all secondary keybindings if they exist
    if (actualKb && Array.isArray(actualKb.secondary)) {
      for (let i = 0, len = actualKb.secondary.length; i < len; i++) {
        const k = actualKb.secondary[i];
        const kk = decodeKeybinding(k, OS);
        if (kk) {
          // Note the negative weight modifier (-i-1) to ensure secondary bindings have lower priority
          result.add(this._registerDefaultKeybinding(kk, rule.id, rule.args, rule.weight, -i - 1, rule.when));
        }
      }
    }
    return result;  // Return composite disposable to unregister all bindings
  }
}

// Singleton instance of the registry
export const KeybindingsRegistry: IKeybindingsRegistry = new KeybindingsRegistryImpl();

// Example Usage: Register Ctrl+S to save the file
KeybindingsRegistry.registerKeybindingRule({
  id: 'workbench.action.files.save',      // Command to execute
  primary: KeyMod.CtrlCmd | KeyCode.KeyS, // Key combination (uses bitwise OR to combine modifiers and keys)
  weight: KeybindingWeight.WorkbenchContrib,  // Priority level
  when: undefined,                        // No context condition - applies everywhere
});

KeybindingService: Capturing Key Presses

Finally, the KeybindingService captures keyboard events and turns them into command executions.

// Service identifier interface
export const IKeybindingService = createDecorator<IKeybindingService>('keybindingService');

export interface IKeybindingService {
  readonly _serviceBrand: undefined;
  // Additional methods defined in implementation
}

// Abstract base implementation with core logic
export abstract class AbstractKeybindingService extends Disposable implements IKeybindingService {
  // Other method

  // Main dispatch method that handles keyboard events
  protected _dispatch(e: IKeyboardEvent, target: IContextKeyServiceTarget): boolean {
    return this._doDispatch(this.resolveKeyboardEvent(e), target);
  }

  // Core dispatch logic that determines which command to run
  private _doDispatch(userKeypress: ResolvedKeybinding, target: IContextKeyServiceTarget): boolean {
    let shouldPreventDefault = false;

    // Extract chord information from the keypress
    let userPressedChord: string | null = null;
    let currentChords: string[] | null = null;

    [userPressedChord,] = userKeypress.getDispatchChords();
    currentChords = this._currentChords.map(({ keypress }) => keypress);

    if (userPressedChord === null) { return shouldPreventDefault }

    // Get current context (for when-clause evaluation)
    const contextValue = this._contextKeyService.getContext(target);
    const keypressLabel = userKeypress.getLabel();

    // Resolve the keybinding using the current context and chord state
    const resolveResult = this._getResolver().resolve(contextValue, currentChords, userPressedChord);

    switch (resolveResult.kind) {
        // Other cases omitted...

      case ResultKind.KbFound: {
        // A command was found for this keybinding
        if (this.inChordMode) {
          this._leaveChordMode();
        }

        // Determine if default browser behavior should be prevented
        if (!resolveResult.isBubble) {
          shouldPreventDefault = true;
        }
        this._currentlyDispatchingCommandId = resolveResult.commandId;

        // Execute the resolved command with optional arguments
        try {
          if (typeof resolveResult.commandArgs === 'undefined') {
            this._commandService.executeCommand(resolveResult.commandId)
              .then(undefined, err => this._notificationService.warn(err));
          } else {
            this._commandService.executeCommand(resolveResult.commandId, resolveResult.commandArgs)
              .then(undefined, err => this._notificationService.warn(err));
          }
        } finally {
          this._currentlyDispatchingCommandId = null;
        }
      }
    }
  }
}

// Concrete implementation for standalone editor scenarios
export class StandaloneKeybindingService extends AbstractKeybindingService {
  private _cachedResolver: KeybindingResolver | null;     // Caches resolved keybindings
  private _dynamicKeybindings: IKeybindingItem[];         // User-defined keybindings
  private readonly _domNodeListeners: DomNodeListeners[]; // DOM event listeners

  constructor() {
    super();

    this._cachedResolver = null;
    this._dynamicKeybindings = [];
    this._domNodeListeners = [];

    // Helper to add keyboard event listeners to a DOM node
    const addContainer = (domNode: HTMLElement) => {
      const disposables = new DisposableStore();

      // Listen for standard key down events
      disposables.add(dom.addDisposableListener(domNode, dom.EventType.KEY_DOWN, (e: KeyboardEvent) => {
        const keyEvent = new StandardKeyboardEvent(e);
        const shouldPreventDefault = this._dispatch(keyEvent, keyEvent.target);
        if (shouldPreventDefault) {
          keyEvent.preventDefault();
          keyEvent.stopPropagation();
        }
      }));

      // Listen for key up events (needed for single modifier chord keybindings)
      disposables.add(dom.addDisposableListener(domNode, dom.EventType.KEY_UP, (e: KeyboardEvent) => {
        const keyEvent = new StandardKeyboardEvent(e);
        const shouldPreventDefault = this._singleModifierDispatch(keyEvent, keyEvent.target);
        if (shouldPreventDefault) {
          keyEvent.preventDefault();
        }
      }));

      this._domNodeListeners.push(new DomNodeListeners(domNode, disposables));
    };

    // Add listeners to code editors
    const addCodeEditor = (codeEditor: ICodeEditor) => {
      if (codeEditor.getOption(EditorOption.inDiffEditor)) {
        return;  // Skip editors that are part of diff views
      }
      addContainer(codeEditor.getContainerDomNode());
    };

    // Add listeners to all existing code editors
    codeEditorService.listCodeEditors().forEach(addCodeEditor);

    // Add listeners to new code editors as they're created
    this._register(codeEditorService.onCodeEditorAdd(addCodeEditor));
  }

  // Creates the resolver that maps key presses to commands
  protected _getResolver(): KeybindingResolver {
    if (!this._cachedResolver) {
      // Combine default keybindings with user-defined ones
      const defaults = this._toNormalizedKeybindingItems(KeybindingsRegistry.getDefaultKeybindings(), true);
      const overrides = this._toNormalizedKeybindingItems(this._dynamicKeybindings, false);
      this._cachedResolver = new KeybindingResolver(defaults, overrides, (str) => this._log(str));
    }
    return this._cachedResolver;
  }
}

A Complete Example: Inside VSCode Core

Let's look at a more complete example of how VSCode itself uses this architecture:

// Inside VSCode core

// 1. Define a service interface
export interface IMyService {
  readonly _serviceBrand: undefined;
  doSomething(text: string): void;
}

// 2. Implement the service
class MyService implements IMyService {
  readonly _serviceBrand: undefined;

  constructor(
    @INotificationService private readonly notificationService: INotificationService
  ) {}

  doSomething(text: string): void {
    this.notificationService.info(`Did something with: ${text}`);
  }
}

// 3. Register the service in the DI container
registerSingleton(IMyService, MyService);

// 4. Register a command that uses the service
CommandsRegistry.registerCommand('myFeature.doSomething', (accessor, text: string) => {
  const myService = accessor.get(IMyService);
  myService.doSomething(text);
});

// 5. Register a keybinding for the command
KeybindingsRegistry.registerKeybindingRule({
  id: 'myFeature.doSomething',
  primary: KeyMod.CtrlCmd | KeyCode.KeyD
});

// 6. Register the command in the editor's context menu
MenuRegistry.appendMenuItem(MenuId.EditorContext, {
  command: {
    id: 'myFeature.doSomething',
    title: 'Do Something',
  },
  group: '1_modification'
});

This example:

Defines a service that can show notifications
Registers the service in VSCode's dependency injection container
Creates a command that uses the service
Maps Ctrl+D (or Cmd+D on Mac) to the command
Adds the command to the editor's context menu

Extension API: A Different Approach

When building VSCode extensions, you use a simplified API that abstracts the internal architecture:

// Inside a VSCode extension

// 1. Activate the extension
export function activate(context: vscode.ExtensionContext) {

  // 2. Register a command
  const disposable = vscode.commands.registerCommand('myExtension.doSomething', async (text?: string) => {
    // If text not provided, prompt user
    if (!text) {
      text = await vscode.window.showInputBox({
        prompt: 'Enter text'
      });

      if (!text) {
        return; // User cancelled
      }
    }

    // Show notification
    vscode.window.showInformationMessage(`Did something with: ${text}`);
  });

  // 3. Register the command for disposal when extension deactivates
  context.subscriptions.push(disposable);
}

Package.json configuration for keybindings and menus

{
  "contributes": {
    "commands": [
      {
        "command": "myExtension.doSomething",
        "title": "Do Something"
      }
    ],
    "keybindings": [
      {
        "command": "myExtension.doSomething",
        "key": "ctrl+d",
        "mac": "cmd+d"
      }
    ],
    "menus": {
      "editor/context": [
        {
          "command": "myExtension.doSomething",
          "group": "1_modification"
        }
      ]
    }
  }
}

The extension API:

Uses vscode.commands.registerCommand instead of direct CommandsRegistry access
Accesses VSCode services through the vscode namespace API instead of dependency injection
Defines keybindings declaratively in package.json instead of programmatically
Still follows the same command execution flow under the hood

Core vs. Extension: Key Differences

Here are the key differences between VSCode core and extension implementation:

Command Registration
- VSCode Core: CommandsRegistry.registerCommand directly
- Extension: vscode.commands.registerCommand API
Service Access
- VSCode Core: Through dependency injection with accessor.get(IService)
- Extension: Through the vscode namespace API
Keybinding Registration
- VSCode Core: Programmatically through KeybindingsRegistry.registerKeybindingRule
- Extension: Declaratively in package.json
Command Execution Flow
- VSCode Core: Direct execution within the main process
- Extension: Execution proxied between the main process and extension host

Despite these differences, the underlying architecture remains the same. This is a powerful example of API design - providing a simpler interface for extension developers while maintaining a consistent internal architecture.

Benefits of VSCode's Command Architecture

This architecture provides several benefits:

Unified Execution Model
- The same command execution flow is used regardless of the trigger source
- This ensures consistent behavior and reduces code duplication
Extensibility
- Third-party extensions can add commands without modifying core code
- Commands can be composed to create higher-level functionality
Performance
- Commands are only loaded when needed
- Keybinding matching is optimized for speed
Separation of Concerns
- Each component has a clear, focused responsibility
- This makes the system easier to maintain and extend

Conclusion

VSCode's Commands and Keybindings architecture is a masterful example of software design. By separating concerns into distinct components and creating a unified execution model, it achieves both flexibility and consistency.

Next time you press Ctrl+S to save a file in VSCode, remember the sophisticated system working behind the scenes to make that simple action possible!

VSCode 3 - Event: From Emitters to Disposables

Ryan — Sun, 13 Apr 2025 12:19:31 +0000

At the heart of Visual Studio Code's reactive architecture lies a powerful event system. This system enables components to communicate without tight coupling, leading to a more maintainable and extensible codebase.

This article explores VSCode's event system, how it works, and why it's superior to traditional approaches.

The Problem: Traditional Event Handling

In browser-based JavaScript, event handling typically looks like this:

// Add a listener
button.addEventListener('click', handleClick);

// Later, manually remove it to prevent memory leaks
button.removeEventListener('click', handleClick);

This approach has several drawbacks:

Manual cleanup: Developers must remember to remove listeners
Difficult tracking: It's hard to know which listeners are active
No standardization: Different event sources have different APIs
No type safety: Events and their data aren't typed

VSCode's Solution: A Typed, Disposable Event System

VSCode's event system addresses these issues with three core components:

Emitter: Creates and fires events
Event: A function that registers listeners
Disposable: Handles automatic cleanup

Here's a simple example:

// Service with an event
class DocumentService {
  // Create an emitter
  private readonly _onDidOpenDocument = new Emitter<Document>();

  // Expose only the event (not the emitter)
  readonly onDidOpenDocument = this._onDidOpenDocument.event;

  openDocument(uri: URI): Document {
    // Document opening logic...
    const document = new Document(uri);

    // Fire the event
    this._onDidOpenDocument.fire(document);

    return document;
  }
}

// Component using the event
class DocumentListener extends Disposable {
  constructor(private documentService: DocumentService) {
    super();

    // Register for the event
    this._register(documentService.onDidOpenDocument(document => {
      console.log(`Document opened: ${document.uri.toString()}`);
    }));
  }
}

Visualizing the Flow

The event system follows this flow:

┌──────────────────┐              ┌──────────────────────┐
│  DocumentService │              │   DocumentListener   │
└────────┬─────────┘              └──────────┬───────────┘
         │                                   │
         │ 1. Creates                        │
         ▼                                   │
┌─────────────────┐                          │
│     Emitter     │                          │
│                 │                          │
│  ┌───────────┐  │  2. Registers listener   │
│  │ listeners │◄─┼──────────────────────────┘
│  │   array   │  │
│  └───────────┘  │                Returns
│                 │                Disposable
│                 ├─────────────────────────►
└────────┬────────┘
         │
         │ 3. Fires event
         │    (calls listeners)
         ▼
     Notification

How the Event System Works

Let's examine the implementation details to understand how this elegant system functions.

The Emitter Class

At its core, an Emitter manages a list of listeners and notifies them when an event occurs:

class Emitter<T> {
  private listeners: Array<(data: T) => void> = [];

  // The event function that adds listeners
  readonly event = (listener: (data: T) => void): IDisposable => {
    // Add the listener
    this.listeners.push(listener);

    // Return a disposable for removal
    return {
      dispose: () => {
        const idx = this.listeners.indexOf(listener);
        if (idx >= 0) {
          this.listeners.splice(idx, 1);
        }
      }
    };
  };

  // Notify all listeners
  fire(data: T): void {
    // Create a copy to handle listeners that might remove themselves
    const listeners = [...this.listeners];
    for (const listener of listeners) {
      listener(data);
    }
  }
}

The Disposable Class

The Disposable class is the foundation of VSCode's resource management system. It tracks resources that need cleanup and handles their disposal:

class Disposable {
  private _toDispose = new Set<IDisposable>();

  // Register a disposable for automatic cleanup
  protected _register<T extends IDisposable>(disposable: T): T {
    this._toDispose.add(disposable);
    return disposable;
  }

  // Dispose all registered disposables
  dispose(): void {
    for (const disposable of this._toDispose) {
      disposable.dispose();
    }
    this._toDispose.clear();
  }
}

This class provides several key benefits:

Centralized cleanup: All resources are managed in one place
Hierarchical disposal: Disposables can contain other disposables
Automatic tracking: No need to manually track each resource
Fluent API: The _register method returns the disposable for further use

When you call documentService.onDidOpenDocument(listener):

You're calling the function stored in onDidOpenDocument
This function adds your listener to the emitter's array
It returns a disposable that can remove your listener
Later, when the emitter fires, your listener is called

The Connection: with Workbench Contributions

This event system integrates perfectly with VSCode's workbench contributions and the _register method:

class GitStatusFeature extends Disposable implements IWorkbenchContribution {
  static ID = 'workbench.contrib.gitStatus';

  constructor(
    @IGitService private gitService: IGitService,
    @IStatusBarService private statusBarService: IStatusBarService
  ) {
    super();

    // Create status bar item
    const statusItem = statusBarService.createStatusbarItem();
    statusItem.text = 'Git: clean';
    statusItem.show();

    // Register the item for disposal
    this._register(statusItem);

    // Register for git repository changes
    this._register(gitService.onDidChangeRepository(repo => {
      this.updateStatus(repo, statusItem);
    }));
  }

  private updateStatus(repo: IGitRepository, item: IStatusBarItem): void {
    if (repo.getChanges().length > 0) {
      item.text = `Git: ${repo.getChanges().length} changes`;
    } else {
      item.text = 'Git: clean';
    }
  }
}

registerWorkbenchContribution2(
  GitStatusFeature.ID,
  GitStatusFeature,
  WorkbenchPhase.AfterRestored
);

When this contribution is disposed:

The _register method has stored all disposables
The base Disposable class's dispose method is called
All registered disposables have their dispose methods called
The event listeners are removed
The status bar item is removed

This happens automatically without the developer having to track and clean up each resource individually.

The Benefits of VSCode's Event System

1. Automatic Cleanup

With traditional browser events:

// Need to manually remove
element.removeEventListener('click', handler);

With VSCode's system:

// Automatic cleanup when the component is disposed
this._register(service.onEvent(handler));

2. Type Safety

The generic type parameter ensures type safety:

// The emitter is typed to emit Document objects
private readonly _onDidOpenDocument = new Emitter<Document>();

// The listener receives a Document parameter
documentService.onDidOpenDocument(document => {
  // TypeScript knows 'document' is a Document
  console.log(document.uri.toString());
});

3. Consistent API

All events follow the same pattern:

Service events are named onDidSomething
All event handlers take a single parameter
All event subscriptions return disposables

This consistency makes the codebase more maintainable.

4. Event Composition

VSCode's system allows for powerful event composition:

// Create an event that only fires for certain conditions
const onDidOpenJavaFile = Event.filter(
  documentService.onDidOpenDocument,
  document => document.languageId === 'java'
);

// Use the filtered event
this._register(onDidOpenJavaFile(document => {
  // Only called for Java files
}));

Comparison with Browser Events

Let's compare VSCode's event system with traditional browser events:

Feature	Browser Events	VSCode Events
Cleanup	Manual removeEventListener	Automatic with disposables
Type Safety	None (vanilla JS)	Full TypeScript support
API Consistency	Varies by event source	Consistent pattern
Composition	Limited	Rich composition support
Event Creation	Complex	Simple Emitter class
Memory Leaks	Common problem	Largely prevented

Conclusion

VSCode's event system represents a sophisticated approach to component communication that addresses many of the shortcomings of traditional event models. By combining typed events, automatic resource management, and a consistent API, it creates a foundation for building complex, reactive applications that remain maintainable.

The system's integration with workbench contributions and the dependency injection system creates a cohesive architecture where:

Services emit events when things change
Components listen for relevant events
The disposable pattern ensures proper cleanup
Changes propagate efficiently through the system

The combination of Emitter, Event, and Disposable creates a powerful reactive programming model that scales well to applications of any size, providing clear separation of concerns while maintaining high performance.

VSCode 2 - Workbench Contributions

Ryan — Sun, 13 Apr 2025 12:17:07 +0000

Visual Studio Code's architecture is a masterclass in building extensible software. One of its most powerful concepts is the Workbench Contribution system, which allows features to initialize at specific times during startup.

This article explores how VSCode uses registerWorkbenchContribution2 to create a responsive, modular editor that loads efficiently.

The Problem: Startup Performance vs. Feature Richness

Modern code editors need to balance two competing requirements:

Fast startup: Users expect the editor to open quickly
Rich features: Users want powerful functionality

If all features initialize simultaneously at startup, the editor becomes slow to load. But if features aren't ready when needed, the user experience suffers.

VSCode's Solution: Phased Initialization

VSCode solves this with a system that loads features in phases, using registerWorkbenchContribution2. This function registers components to be initialized at specific points in the startup sequence.

Here's a simple example:

class GitStatusFeature implements IWorkbenchContribution {
  static ID = 'workbench.contrib.gitStatus';

  constructor(
    @IGitService private gitService: IGitService
  ) {
    // Initialization code runs when this component is created
    console.log('Git status feature initialized');
  }
}

// Register to run during the AfterRestored phase
registerWorkbenchContribution2(
  GitStatusFeature.ID,
  GitStatusFeature,
  WorkbenchPhase.AfterRestored
);

Understanding the Workbench Phases

VSCode defines four main phases for workbench contributions:

export const enum WorkbenchPhase {
  // Very early in startup - blocks the UI from showing
  BlockStartup = LifecyclePhase.Starting,

  // Services are ready, UI is about to restore - blocks UI
  BlockRestore = LifecyclePhase.Ready,

  // Views, panels and editors have restored
  AfterRestored = LifecyclePhase.Restored,

  // After everything else (2-5 seconds after startup)
  Eventually = LifecyclePhase.Eventually
}

How It Works: The Lifecycle

When VSCode starts:

The workbench begins initialization
Each lifecycle phase is reached sequentially
When a phase is reached, all contributions registered for that phase are created
The constructor of each contribution runs, initializing the feature

Here's a visual representation of the process:

┌─────────────────┐
│    VSCode       │
│    Startup      │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  BlockStartup   │──┐
└────────┬────────┘  │
         │           │ Create contributions
         │           │ registered for
         │           │ BlockStartup
         ▼           │
┌─────────────────┐  │
│  BlockRestore   │──┤
└────────┬────────┘  │
         │           │ Create contributions
         │           │ registered for
         │           │ BlockRestore
         ▼           │
┌─────────────────┐  │
│  AfterRestored  │──┤
└────────┬────────┘  │
         │           │ Create contributions
         │           │ registered for
         │           │ AfterRestored
         ▼           │
┌─────────────────┐  │
│   Eventually    │──┘
└─────────────────┘   Create contributions
                      registered for
                      Eventually

The Connection: with Dependency Injection

Workbench contributions leverage VSCode's dependency injection system. When a contribution is instantiated, its dependencies are automatically resolved:

class SearchFeature implements IWorkbenchContribution {
  static ID = 'workbench.contrib.search';

  constructor(
    @ISearchService private searchService: ISearchService,
    @IWorkspaceService private workspaceService: IWorkspaceService
  ) {
    // Both services are automatically injected
  }
}

This creates a powerful pattern where:

Services are registered with registerSingleton
Features are registered with registerWorkbenchContribution2
Services are automatically injected into features
Features initialize at the appropriate time

The Power of Disposable

Another key aspect of workbench contributions is resource management through the Disposable class and its _register method.

A simple implementation of Disposable looks like this:

class Disposable {
  private _toDispose = new Set<IDisposable>();

  protected _register<T extends IDisposable>(disposable: T): T {
    this._toDispose.add(disposable);
    return disposable;
  }

  dispose(): void {
    for (const disposable of this._toDispose) {
      disposable.dispose();
    }
    this._toDispose.clear();
  }
}

Most workbench contributions extend this class:

class EditorFeature extends Disposable implements IWorkbenchContribution {
  static ID = 'workbench.contrib.editor';

  constructor(
    @IEditorService private editorService: IEditorService
  ) {
    super(); // Initialize Disposable

    // Register event listener for cleanup
    this._register(editorService.onDidActiveEditorChange(() => {
      this.updateUI();
    }));
  }

  private updateUI(): void {
    // Update UI based on editor changes
  }
}

When VSCode shuts down or the contribution is no longer needed:

VSCode calls dispose() on the contribution
The contribution's dispose() calls dispose() on all registered disposables
This ensures all resources are properly cleaned up

A Complete Workbench Contribution Example

Let's look at a more complete example:

class FileExplorerFeature extends Disposable implements IWorkbenchContribution {
  static ID = 'workbench.contrib.fileExplorer';

  // Status bar item we'll create
  private statusItem: IStatusbarItem;

  constructor(
    @IFileService private fileService: IFileService,
    @IWorkspaceService private workspaceService: IWorkspaceService,
    @IStatusbarService private statusbarService: IStatusbarService
  ) {
    super();

    // Create status bar item
    this.statusItem = this.statusbarService.createStatusbarItem();
    this.statusItem.text = 'Loading...';
    this.statusItem.show();

    // Register the status item for disposal
    this._register(this.statusItem);

    // Register workspace folder change listener
    this._register(this.workspaceService.onDidChangeWorkspaceFolders(() => {
      this.updateFileCount();
    }));

    // Initial update
    this.updateFileCount();
  }

  private async updateFileCount(): void {
    const roots = this.workspaceService.getWorkspace().folders;
    if (roots.length === 0) {
      this.statusItem.text = 'No folder opened';
      return;
    }

    try {
      const files = await this.fileService.listFiles(roots[0].uri);
      this.statusItem.text = `Files: ${files.length}`;
    } catch (e) {
      this.statusItem.text = 'Error counting files';
    }
  }
}

// Register to initialize after the UI is restored
registerWorkbenchContribution2(
  FileExplorerFeature.ID,
  FileExplorerFeature,
  WorkbenchPhase.AfterRestored
);

This contribution:

Creates a status bar item showing file count
Listens for workspace folder changes
Updates when folders change
Properly cleans up when disposed

Best Practices for Workbench Contributions

When creating workbench contributions, follow these guidelines:

1. Choose the Right Phase

// Critical functionality - BlockRestore
registerWorkbenchContribution2(
  EditorFeature.ID,
  EditorFeature,
  WorkbenchPhase.BlockRestore
);

// Non-critical enhancement - Eventually
registerWorkbenchContribution2(
  CodeMetricsFeature.ID,
  CodeMetricsFeature,
  WorkbenchPhase.Eventually
);

2. Keep Constructors Fast

constructor(/*...*/) {
  super();

  // Do minimal work here
  this.initialize();
}

private async initialize(): Promise<void> {
  // Do heavier initialization asynchronously
}

3. Always Clean Up Resources

constructor(/*...*/) {
  super();

  // Register everything that needs cleanup
  this._register(service.onEvent(() => {}));
  this._register(new CustomDisposable());
}

4. Use Event-Based Architecture

constructor(/*...*/) {
  super();

  // React to events rather than polling
  this._register(fileService.onDidFileChange(e => {
    if (e.affects(this.currentFile)) {
      this.refresh();
    }
  }));
}

The Benefits of Workbench Contributions

This architecture provides several advantages:

Performance: Features load only when needed
Modularity: Each feature is self-contained
Resource management: Automatic cleanup prevents leaks
Extensibility: Third-party extensions use the same pattern

Conclusion

VSCode's workbench contribution system represents a sophisticated approach to managing feature initialization in a complex application. By combining phased initialization with dependency injection and automatic resource cleanup, it creates an architecture that's both performant and maintainable.

Understanding this pattern is valuable not just for VSCode extension developers, but for anyone building complex applications that need to balance startup performance with rich functionality. The principles of phased initialization, dependency injection, and automatic resource management can be applied in many contexts to create more responsive and maintainable software.

As you design your own applications, consider how separating initialization into phases might improve both the user experience and code organization. The registerWorkbenchContribution2 pattern demonstrates that with thoughtful architecture, you can have both rich features and good performance.

VSCode 1 - Service : Dependency Injection(DI)

Ryan — Sun, 13 Apr 2025 12:14:16 +0000

In modern software development, particularly with large-scale applications like Visual Studio Code, managing dependencies between components becomes increasingly complex. VSCode's approach to this challenge is a robust dependency injection (DI) system with many services, centered around the registerSingleton function.

This article explores how VSCode's DI system works, why it's valuable, and how it compares to other approaches.

The Problem: Component Dependencies

In any large application, components need to work together. Consider a simple text editor:

The EditorView displays text and handles user input
The FileService loads and saves files
The ThemeService manages visual appearance

Without dependency injection, components might create their dependencies directly:

class EditorView {
  constructor() {
    // Directly creating dependencies
    this.fileService = new FileService();
    this.themeService = new ThemeService();
  }

  openFile(path) {
    const content = this.fileService.readFile(path);
    this.displayContent(content);
  }
}

This approach leads to several problems:

Tight coupling: The editor is permanently tied to specific implementations
Testing difficulty: You can't easily substitute mock services for tests
Flexibility loss: Changing implementations requires modifying multiple classes

VSCode's Solution: The registerSingleton Pattern

VSCode elegantly solves these problems with a system built around three core concepts:

Service interfaces: Define what a service does, not how it does it
Service identifiers: Unique tokens that represent services
Service registration: The process of mapping interfaces to implementations

Here's a simplified example:

// 1. Define a service interface
interface IFileService {
  readFile(path: string): Promise<string>;
  writeFile(path: string, content: string): Promise<void>;
}

// 2. Create a service identifier
const IFileService = createDecorator<IFileService>('fileService');

// 3. Implement the service
class FileService implements IFileService {
  readFile(path: string): Promise<string> {
    // Implementation
    return fs.promises.readFile(path, 'utf8');
  }

  writeFile(path: string, content: string): Promise<void> {
    // Implementation
    return fs.promises.writeFile(path, content);
  }
}

// 4. Register the service
registerSingleton(IFileService, FileService, InstantiationType.Eager);

When you call registerSingleton(IFileService, FileService, InstantiationType.Eager), you're telling VSCode:

"When a component needs an IFileService..."
"...create an instance of FileService..."
"...and provide that instance to the component."

But notice, services are always lazily created, even if you register them as Eager.

The magic happens when components declare their dependencies like FileService in Typescript:

class EditorView {
  constructor(
    @IFileService private fileService: IFileService,
    @IThemeService private themeService: IThemeService
  ) {
    // Services are injected, not created
  }

  openFile(path) {
    const content = this.fileService.readFile(path);
    this.displayContent(content);
  }
}

Visualizing the Dependency Injection Flow

Here's how the system works at runtime:

┌───────────────────┐     requests       ┌───────────────────────┐
│                   │ ---------------->  │                       │
│    EditorView     │                    │ InstantiationService  │
│                   │ <----------------  │                       │
└───────────────────┘   injects services └─────────┬─────────────┘
                                                   │
                                                   │ looks up
                                                   ▼
┌───────────────────┐                 ┌─────────────────────┐
│                   │                 │                     │
│    FileService    │ <-------------- │  Service Registry   │
│                   │    creates      │                     │
└───────────────────┘                 └─────────────────────┘

Benefits of VSCode's Approach

1. Decoupling Components

Components depend on interfaces, not implementations. This means:

The EditorView only knows about the IFileService interface
The concrete FileService can be replaced without changing consumers
Components focus on their own responsibilities

2. Simplified Testing

With DI, testing becomes straightforward:

// Create a mock service
const mockFileService: IFileService = {
  readFile: jest.fn().mockResolvedValue("test content"),
  writeFile: jest.fn().mockResolvedValue(undefined)
};

// Test with the mock
const editor = new EditorView(mockFileService, mockThemeService);
await editor.openFile("test.txt");

// Verify the mock was called
expect(mockFileService.readFile).toHaveBeenCalledWith("test.txt");

3. Supporting Different Environments

VSCode runs on multiple platforms (desktop, web, remote). The DI system allows for platform-specific implementations:

if (platform === 'web') {
  registerSingleton(IFileService, WebFileService);
} else {
  registerSingleton(IFileService, DesktopFileService);
}

Components using IFileService remain unchanged while getting environment-appropriate implementations.

4. Extension Ecosystem Support

For an extensible platform like VSCode, DI creates clear extension points:

// An extension can replace a standard service
context.registerServiceProvider(ISearchService, BetterSearchService);

A Complete Example

Let's look at a more complete example showing the full pattern:

// 1. Service interface and identifier
interface ILogService {
  log(message: string): void;
  error(message: string, error?: Error): void;
}
const ILogService = createDecorator<ILogService>('logService');

// 2. Service implementation
class ConsoleLogService implements ILogService {
  log(message: string): void {
    console.log(`[LOG] ${message}`);
  }

  error(message: string, error?: Error): void {
    console.error(`[ERROR] ${message}`, error);
  }
}

// 3. Service registration
registerSingleton(ILogService, ConsoleLogService, InstantiationType.Eager);

// 4. Service consumption
class DocumentProcessor {
  constructor(
    @ILogService private readonly logService: ILogService,
    @IFileService private readonly fileService: IFileService
  ) {}

  async processDocument(path: string): Promise<void> {
    try {
      this.logService.log(`Processing document: ${path}`);
      const content = await this.fileService.readFile(path);
      // Process content...
      this.logService.log(`Document processed successfully`);
    } catch (e) {
      this.logService.error(`Failed to process document`, e);
    }
  }
}

About Instantiation Types

VSCode's DI system offers control over when services are created:

// Created immediately at startup
registerSingleton(ILogService, ConsoleLogService, InstantiationType.Eager);

// Created when first requested (default)
registerSingleton(ISearchService, SearchService, InstantiationType.Delayed);

This allows performance optimization by:

Loading critical services immediately
Deferring non-essential services until needed

Advanced 1: Comparison with Nest.js

If you're familiar with Nest.js, you'll notice striking similarities:

// Nest.js approach
@Injectable()
class LogService {
  log(message: string): void {
    console.log(`[LOG] ${message}`);
  }
}

@Controller()
class AppController {
  constructor(private readonly logService: LogService) {}

  @Get()
  handleRequest() {
    this.logService.log('Handling request');
    return 'Hello World';
  }
}

Both systems use:

Decorator-based injection
Constructor injection
Singleton services by default
A centralized container that manages instances

The key difference is that VSCode's system is more focused on interface/implementation separation, while Nest.js often injects concrete classes directly.

Advanced 2: source code for implementations

createDecorator

export namespace _util {
  export const serviceIds = new Map<string, ServiceIdentifier<any>>();

  export const DI_TARGET = '$di$target';
  export const DI_DEPENDENCIES = '$di$dependencies';

  export function getServiceDependencies(ctor: any): { id: ServiceIdentifier<any>; index: number }[] {
    return ctor[DI_DEPENDENCIES] || [];
  }
}

export interface ServiceIdentifier<T> {
  (...args: any[]): void;
  type: T;
}

function storeServiceDependency(id: Function, target: Function, index: number): void {
  if ((target as any)[_util.DI_TARGET] === target) {
    (target as any)[_util.DI_DEPENDENCIES].push({ id, index });
  } else {
    (target as any)[_util.DI_DEPENDENCIES] = [{ id, index }];
    (target as any)[_util.DI_TARGET] = target;
  }
}

export function createDecorator<T>(serviceId: string): IServiceIdentifier<T> {
  if (_util.serviceIds.has(serviceId)) {
    return _util.serviceIds.get(serviceId)!;
  }

  const id = <any>function (target: Function, key: string, index: number) {
    storeServiceDependency(id, target, index);
  };

  id.toString = () => serviceId;

  _util.serviceIds.set(serviceId, id);
  return id;
}

ServiceCollection

export class ServiceCollection {
  private _entries = new Map<ServiceIdentifier<any>, any>();

  constructor(...entries: [ServiceIdentifier<any>, any][]) {
    for (const [id, service] of entries) {
      this.set(id, service);
    }
  }

  set<T>(id: ServiceIdentifier<T>, instanceOrDescriptor: T | SyncDescriptor<T>): T | SyncDescriptor<T> {
    const result = this._entries.get(id);
    this._entries.set(id, instanceOrDescriptor);
    return result;
  }

  has(id: ServiceIdentifier<any>): boolean {
    return this._entries.has(id);
  }

  get<T>(id: ServiceIdentifier<T>): T | SyncDescriptor<T> {
    return this._entries.get(id);
  }
}

registerSingleton(simply version)

const _globalServiceCollection = new ServiceCollection();

export const enum InstantiationType {
  Eager = 0,
  Delayed = 1
}

export function registerSingleton<T>(
  id: IServiceIdentifier<T>, 
  ctor: new (...args: any[]) => T, 
  instantiationType: InstantiationType = InstantiationType.Delayed
): void {
  // In actual VSCode, this would use an internal mechanism for serviceCollection instead of _globalServiceCollection
  if (instantiationType === InstantiationType.Eager) {
    // Create immediately
    const instance = new ctor();
    _globalServiceCollection.set(id, instance);
  } else {
    // Delay
    _globalServiceCollection.set(id, ctor);
  }
}

InstantiationService(simple version)

export class InstantiationService {
  private _serviceCollection: ServiceCollection;

  constructor(serviceCollection: ServiceCollection) {
    this._serviceCollection = serviceCollection;
  }

  createInstance<T>(ctor: new (...args: any[]) => T, ...args: any[]): T {
    // Simplified implementation - in reality, VSCode does more complex dependency resolution
    return new ctor(...args);
  }

  getService<T>(serviceId: IServiceIdentifier<T>): T {
    // Get the service or its constructor
    const instanceOrCtor = this._serviceCollection.get(serviceId);

    // If it's already an instance, return it
    if (typeof instanceOrCtor !== 'function') {
      return instanceOrCtor;
    }

    // Otherwise, create an instance
    const instance = this.createInstance(instanceOrCtor);
    // Save the instance for future use (singleton pattern)
    this._serviceCollection.set(serviceId, instance);
    return instance;
  }
}

LoggerService

interface ILoggerService {
  log(message: string): void;
}

const ILoggerService = createDecorator<ILoggerService>('loggerService');

class LoggerService implements ILoggerService {
  log(message: string): void {
    console.log(`[Logger] ${message}`);
  }
}

bootstrapApplication

function bootstrapApplication() {
  _globalServiceCollection = new ServiceCollection();

  registerSingleton(ILoggerService, LoggerService, InstantiationType.Delayed);

  const instantiationService = new InstantiationService(_globalServiceCollection);
  return instantiationService;
}

// Bootstrap the application
const instantiationService = bootstrapApplication();

// Get and use a service
const loggerService = instantiationService.getService(ILoggerService);
loggerService.log('Hello, world!');

Conclusion

VSCode's dependency injection system, centered around registerSingleton, provides a clean solution to the challenge of component dependencies in large applications. By separating interfaces from implementations and centralizing service creation, it creates a more testable, flexible, and maintainable codebase.

The pattern has proven so effective that similar approaches appear in many modern frameworks, from Angular to Nest.js. Understanding this architectural pattern helps not just when working with VSCode's source code, but when designing any complex application with multiple interconnected components.

As you build your own applications, consider how this pattern might help manage the growing complexity of component relationships, particularly if you anticipate needs for testing, platform-specific implementations, or future extensibility.