SuipulseHub

Event Handling

This guide covers how to handle events and real-time updates in SuiPulse.

Event Types

Stream Events

// Stream Created Event
{
  type: `${packageId}::storage::StreamCreated`,
  parsedJson: {
    stream_id: string;
    name: string;
    description: string;
  }
}

// Stream Updated Event
{
  type: `${packageId}::storage::StreamUpdated`,
  parsedJson: {
    stream_id: string;
    version: number;
  }
}

// Snapshot Created Event
{
  type: `${packageId}::storage::SnapshotCreated`,
  parsedJson: {
    snapshot_id: string;
    stream_id: string;
  }
}

Event Subscription

Subscribe to Stream Events

// Subscribe to stream creation events
const unsubscribe = await suiPulse.subscribeToEvents(
  "StreamCreated",
  (event) => {
    console.log("New stream created:", event.parsedJson.stream_id);
  }
);

// Subscribe to stream update events
const unsubscribe = await suiPulse.subscribeToEvents(
  "StreamUpdated",
  (event) => {
    console.log("Stream updated:", event.parsedJson.stream_id);
  }
);

// Subscribe to snapshot creation events
const unsubscribe = await suiPulse.subscribeToEvents(
  "SnapshotCreated",
  (event) => {
    console.log("New snapshot created:", event.parsedJson.snapshot_id);
  }
);

// Later: stop listening for updates
unsubscribe();

Event Handling Example

Monitor Stream Updates

class StreamMonitor {
  private subscriptions: Map<string, () => void> = new Map();

  async monitorStream(streamId: string) {
    const unsubscribe = await suiPulse.subscribeToEvents(
      "StreamUpdated",
      (event) => {
        if (event.parsedJson.stream_id === streamId) {
          this.handleStreamUpdate(event);
        }
      }
    );
    this.subscriptions.set(streamId, unsubscribe);
  }

  private handleStreamUpdate(event: any) {
    console.log(
      `Stream ${event.parsedJson.stream_id} updated to version ${event.parsedJson.version}`
    );
    // Add your custom handling logic here
  }

  stopMonitoring(streamId: string) {
    const unsubscribe = this.subscriptions.get(streamId);
    if (unsubscribe) {
      unsubscribe();
      this.subscriptions.delete(streamId);
    }
  }

  cleanup() {
    this.subscriptions.forEach((unsubscribe) => unsubscribe());
    this.subscriptions.clear();
  }
}

Error Handling

Event Error Handling

try {
  const unsubscribe = await suiPulse.subscribeToEvents(
    "StreamUpdated",
    (event) => {
      console.log("Stream updated:", event);
    }
  );
} catch (error) {
  console.error("Failed to subscribe to events:", error);
  // Implement retry logic or error recovery
}

Best Practices

  1. Event Management

    • Clean up subscriptions when no longer needed
    • Handle connection state changes
    • Implement proper error handling

  2. Performance

    • Subscribe only to needed events
    • Process events efficiently
    • Monitor event queue size

  3. Reliability

    • Implement retry mechanisms
    • Handle network interruptions
    • Use appropriate timeouts

Example: Real-time Dashboard

class StreamDashboard {
  private subscriptions: Map<string, () => void> = new Map();

  async addStream(streamId: string) {
    const unsubscribe = await suiPulse.subscribeToEvents(
      "StreamUpdated",
      (event) => {
        if (event.parsedJson.stream_id === streamId) {
          this.updateDashboard(streamId, event);
        }
      }
    );
    this.subscriptions.set(streamId, unsubscribe);
  }

  private updateDashboard(streamId: string, event: any) {
    // Update your dashboard UI here
    console.log(`Updating dashboard for stream ${streamId}`);
    console.log("Event data:", event);
  }

  removeStream(streamId: string) {
    const unsubscribe = this.subscriptions.get(streamId);
    if (unsubscribe) {
      unsubscribe();
      this.subscriptions.delete(streamId);
    }
  }

  cleanup() {
    this.subscriptions.forEach((unsubscribe) => unsubscribe());
    this.subscriptions.clear();
  }
}

Next Steps