Event System

The event system is the primary communication mechanism between runtime services, plugins, and UI components. Almost every class in the API package extends EventDispatcher.

EventDispatcher

EventDispatcher<EventTypes> (packages/api/src/lib/events.ts) wraps EventEmitter3:

Methods

Method	Purpose
`on(eventName, listener, context?)`	Subscribe. Returns `EventRef` for manual unsubscription.
`once(eventName, listener, context?)`	One-time subscription.
`off(eventName, listener, context?, once?)`	Unsubscribe by function reference.
`offref(ref: EventRef)`	Unsubscribe using ref.
`trigger(eventName, ...args)`	Emit event.
`emit(eventName, ...args)`	Alias for `trigger`.
`dispatch(eventName, ...args)`	Alias for `trigger`.
`tryTrigger(ref, ...args)`	Safe trigger that catches errors.

Type System

Events are fully typed via a generic map:

class MyService extends EventDispatcher<{
  "file-change": [file: TFile, event: string];
  "load": [];
}> {}

const ref = service.on("file-change", (file, event) => { ... });
service.offref(ref);  // Clean up

Lifecycle Integration

Component.registerEvent(ref) tracks event subscriptions and automatically unsubscribes them when the component is unloaded. This prevents memory leaks in views and plugins.

// In a Plugin or View:
this.registerEvent(
  app.vault.on("modify", (file) => { ... })
);
// Automatically cleaned up on unload

Event Catalog

Vault Events

Event	Arguments	When
`load`	—	File tree loaded from adapter
`create`	`file: TAbstractFile`	File or folder created
`modify`	`file: TAbstractFile`	File content modified
`delete`	`file: TAbstractFile`	File or folder deleted
`rename`	`file: TAbstractFile, oldPath: string`	File or folder renamed/moved
`all`	`event: string, file, context`	Any vault event (discriminated)

Workspace Events

Event	Arguments	When
`active-leaf-change`	`leaf: WorkspaceLeaf`	Active leaf changed
`file-change`	`file: TFile, event: string`	External file modification detected
`layout-change`	`event: WorkspaceLayoutChangeEvent`	A committed restorable layout mutation is persisted
`layout-will-show-overlay`	`event: WorkspaceLayoutDropEvent`	A renderer drop target is deciding whether to expose an overlay
`layout-will-drop`	`event: WorkspaceLayoutDropEvent`	A drag/drop layout mutation is about to commit; listeners may cancel
`layout-did-drop`	`event: WorkspaceLayoutDropEvent`	A drag/drop layout mutation committed successfully
`layout-ready`	—	Layout fully loaded

Current workspace renderer coverage actively emits layout-will-show-overlay, layout-will-drop, layout-did-drop, layout-change, and layout-ready. Workspace also exposes typed layout-drag-start and layout-drag-end helpers for future drag backends, but the current HTML5 renderer path does not yet emit those start/end events consistently.

MetadataCache Events

Event	Arguments	When
`changed`	`file: TFile, data: string, cache: CachedMetadata`	File indexed or re-indexed
`deleted`	`file: TFile, prevCache: CachedMetadata`	File removed from cache
`loaded`	—	Cache loaded from storage

Metadata cache events are intentionally low-level and per-file. Search indexing and other vault-wide derived-state owners may listen broadly, but view surfaces are expected to filter these events to the active file or directly affected reference neighborhood whenever they can do so safely.

PluginManager Events

Event	Arguments	When
`plugins-loaded`	—	All plugins loaded from disk
`plugin-loaded`	`plugin: Plugin`	Single plugin loaded
`plugin-enabled`	`plugin: Plugin`	Plugin enabled
`plugin-disabled`	`plugin: Plugin`	Plugin disabled
`plugin-error`	`error: Error`	Plugin load/enable error
`css-change`	—	Plugin CSS modified

CommandManager Events

Event	Arguments	When
`register`	`command: Command`	Command registered
`unregister`	`command: Command`	Command unregistered

Configuration Events

Event	Arguments	When
`updated`	`{key, value, prev}`	Configuration value changed

Plugin Events

Event	Arguments	When
`enable`	—	Plugin enabled
`disable`	—	Plugin disabled

Editor Events

Event	Arguments	When
`change`	`data: string`	Document content modified

Event Flow Patterns

File Modification Flow

User edits in CodeMirror
  → Editor.save() (debounced 500ms)
    → vault.modify(file, data)
      → vault emits "modify"
        → watch-vault detects change
          → metadataCache processes file
            → metadataCache emits "changed"
              → searchManager.processChange() updates index
              → metadataTypeManager.processChange() updates types

Plugin Load Flow

PluginManager.loadPlugins()
  → reads /.obsidian/plugins/
    → for each: loadPlugin(path)
      → reads manifest.json
      → dynamicImport(main.js)
      → emits "plugin-loaded"
  → reads community-plugins.json
    → for each enabled: enablePlugin(id)
      → plugin.enable() → plugin.onload()
      → loads styles.css → appends <style>
      → emits "plugin-enabled"
  → emits "plugins-loaded"

Keyboard shortcuts

Lapis Notes Architecture Spec