wps-events

WPS Events Guide

Overview

WPS (Wave PubSub) is Wave Terminal's publish-subscribe event system that enables different parts of the application to communicate asynchronously. The system uses a broker pattern to route events from publishers to subscribers based on event types and scopes.

Key Files

• pkg/wps/wpstypes.go - Event type constants and data structures
• pkg/wps/wps.go - Broker implementation and core logic
• pkg/wcore/wcore.go - Example usage patterns

Event Structure

Events in WPS have the following structure:

type WaveEvent struct {
    Event   string   `json:"event"`      // Event type constant
    Scopes  []string `json:"scopes,omitempty"` // Optional scopes for targeted delivery
    Sender  string   `json:"sender,omitempty"` // Optional sender identifier
    Persist int      `json:"persist,omitempty"` // Number of events to persist in history
    Data    any      `json:"data,omitempty"`    // Event payload
}

Adding a New Event Type

Step 1: Define the Event Constant

Add your event type constant to pkg/wps/wpstypes.go:

const (
    Event_BlockClose       = "blockclose"
    Event_ConnChange       = "connchange"
    // ... other events ...
    Event_YourNewEvent     = "your:newevent"  // type: YourEventData (or "none" if no data)
)

Naming Convention:

• Use descriptive PascalCase for the constant name with Event_ prefix
• Use lowercase with colons for the string value (e.g., "namespace:eventname")
• Group related events with the same namespace prefix
• Always add a // type: <TypeName> comment; use // type: none if no data is sent

Step 2: Add to AllEvents

Add your new constant to the AllEvents slice in pkg/wps/wpstypes.go:

var AllEvents []string = []string{
    // ... existing events ...
    Event_YourNewEvent,
}

Step 3: Register in WaveEventDataTypes (REQUIRED)

You must add an entry to WaveEventDataTypes in pkg/tsgen/tsgenevent.go. This drives TypeScript type generation for the event's data field: