@cvo/plugin-sse

Native Server-Sent Events (SSE) support for CVO Framework. SSE is a lightweight, HTTP-based push technology perfect for real-time logs, notifications, and AI streaming responses.

🚀 Features

• Lightweight & Native: Based on standard HTTP, no complex handshake like WebSocket.
• Decorator Support: Define endpoints easily using the @sse decorator.
• Structured Streaming: Send events with optional event names and id tags for reliable reconnection.
• Auto-headers: Automatically handles text/event-stream, no-cache, and keep-alive.
• Global Pushing: Support for pushing messages to specific users or broadcasting to all clients.
• AI Friendly: Ideal for LLM streaming outputs with minimal boilerplate.

🛠 Configuration

Register the plugin in your cvo.config.ts:

import { defineConfig } from '@cvo/core';
import { ssePlugin } from '@cvo/plugin-sse';

export default defineConfig({
  plugins: [
    ssePlugin()
  ]
});

🧠 Usage

Defining an SSE Endpoint

The @sse decorator registers an endpoint. You can inject SSEClient to interact with the connection.

import { sse, SSEClient } from '@cvo/plugin-sse';

@sse('/api/events/time')
export async function streamTime(client: SSEClient, ctx: any) {
  // Send an initial welcome event
  client.send({ message: 'Connected!' }, 'welcome');

  // Push current time every second
  const timer = setInterval(() => {
    client.send({ timestamp: Date.now() });
  }, 1000);
  
  // CRITICAL: Clean up timer when client disconnects
  ctx.res.on('close', () => {
    clearInterval(timer);
  });
}

Global Pushing

Access the plugin instance via useSSE() to push to specific users or broadcast. The plugin automatically tracks clients if a userId is present in ctx.state.user.id or the query string.

import { useSSE } from '@cvo/server';

export async function notifyUser(userId: string) {
  const sse = useSSE();
  
  // Push to a specific user
  sse.sendToUser(userId, { type: 'alert', message: 'New private message' });
  
  // Broadcast to all connected clients
  sse.broadcast({ type: 'system', message: 'System maintenance in 5 minutes' });
}

📦 Client Usage

SSE is natively supported by all modern browsers via the EventSource API.

const eventSource = new EventSource('/api/events/time');

eventSource.onmessage = (event) => {
  console.log('Received:', JSON.parse(event.data));
};

eventSource.addEventListener('welcome', (event) => {
  console.log('Welcome event:', event.data);
});