Chapter 8: SSE / NDJSON Streaming

Streaming Without WebSocket

An AI chatbot types back one token at a time. A dashboard counter ticks up as orders arrive. A notification feed shows events the moment they happen. The data flows from server to client, but you don't need the complexity of WebSocket for it.

Server-Sent Events (SSE) is the browser's built-in streaming protocol. One-directional: server pushes, client listens. It reconnects automatically. It works over HTTP/2. It's simpler than WebSocket for every case where you don't need to send data back.

NDJSON (Newline-Delimited JSON) is the same idea over a regular fetch response. One JSON object per line, streamed as the server generates them. This is how most AI APIs stream tokens — and it supports POST requests and custom headers, which SSE's EventSource does not.

tina4-js wraps both in a single module. One function call opens the stream. Six reactive signals track the state. A pipe function accumulates messages into your signals with a reducer. Auto-reconnect handles dropped connections.

---

1. The SSE Client

The tina4-js SSE client provides:

1. Dual mode — native EventSource for SSE, fetch+ReadableStream for NDJSON
2. Reactive signals — status, connected, lastMessage, lastEvent, error, reconnectCount
3. Auto-reconnect — exponential backoff, configurable attempts
4. Signal piping — stream messages into signals with a reducer

import { sse } from 'tina4js';

---

2. EventSource Mode (Default)

const stream = sse.connect('/api/events');

One line. The browser opens an EventSource connection. Messages arrive as the server sends them.

import { sse, effect } from 'tina4js';

const stream = sse.connect('/api/events');

effect(() => {
  console.log('Status:', stream.status.value);
});

effect(() => {
  if (stream.lastMessage.value) {
    console.log('Received:', stream.lastMessage.value);
  }
});

---

3. Fetch Mode (NDJSON)

EventSource only supports GET requests with no custom headers. For POST requests, Bearer tokens, or NDJSON streaming, use fetch mode:

const stream = sse.connect('/api/chat', {
  mode: 'fetch',
  method: 'POST',
  headers: { 'Authorization': 'Bearer eyJ...' },
  body: { prompt: 'Explain signals in tina4-js' },
});

The client reads the response body as a stream, splits on newlines, and parses each line as JSON. Every parsed object becomes a message.

---

4. Options

const stream = sse.connect('/api/events', {
  mode: 'eventsource',    // 'eventsource' (default) or 'fetch'
  method: 'GET',           // HTTP method (fetch mode only)
  headers: {},             // Custom headers (fetch mode only)
  body: undefined,         // Request body (fetch mode only, auto-stringified)
  reconnect: true,         // Auto-reconnect on disconnect
  reconnectDelay: 1000,    // Initial delay (ms)
  reconnectMaxDelay: 30000,// Max delay after backoff (ms)
  reconnectAttempts: Infinity, // Max attempts
  events: [],              // Named SSE events (eventsource mode only)
  json: true,              // Auto-parse JSON (default: true)
});

Option	Default	Description
mode	'eventsource'	Transport: native EventSource or fetch+ReadableStream
method	'GET'	HTTP method (fetch mode only)
headers	{}	Custom headers (fetch mode only)
body	undefined	Request body (fetch mode, auto JSON.stringify)
reconnect	true	Auto-reconnect on disconnect
reconnectDelay	1000	Initial reconnect delay in ms
reconnectMaxDelay	30000	Max delay for exponential backoff
reconnectAttempts	Infinity	Max reconnect attempts
events	[]	Named SSE events to listen for
json	true	Auto-parse messages as JSON

---

5. Reactive Signals

Every stream exposes six reactive signals:

const stream = sse.connect('/api/events');

stream.status         // Signal<'connecting' | 'open' | 'closed' | 'reconnecting'>
stream.connected      // Signal<boolean>
stream.lastMessage    // Signal<unknown>  — last parsed message
stream.lastEvent      // Signal<string | null>  — SSE event name or null
stream.error          // Signal<Event | Error | null>
stream.reconnectCount // Signal<number>

Use them in effects, computed values, or html templates:

effect(() => {
  if (stream.connected.value) {
    console.log('Stream is live');
  }
});

---

6. Event Handlers

Register listeners for stream events. Every handler returns an unsubscribe function:

const unsub = stream.on('message', (data, event?) => {
  console.log('Data:', data);
  console.log('Event name:', event); // SSE event name or undefined
});

stream.on('open', () => console.log('Connected'));
stream.on('close', () => console.log('Disconnected'));
stream.on('error', (err) => console.error('Error:', err));

// Stop listening
unsub();

---

7. Named Events (EventSource Mode)

SSE supports named events. By default, EventSource only listens for unnamed message events. Pass event names in the options to listen for specific types:

const stream = sse.connect('/api/feed', {
  events: ['user_joined', 'message', 'user_left'],
});

stream.on('message', (data, event) => {
  switch (event) {
    case 'user_joined':
      console.log(`${data.name} joined`);
      break;
    case 'message':
      console.log(`${data.author}: ${data.text}`);
      break;
    case 'user_left':
      console.log(`${data.name} left`);
      break;
  }
});

// The lastEvent signal tracks the most recent event name
effect(() => console.log('Last event type:', stream.lastEvent.value));

---

8. Pipe to Signal

The pipe pattern streams messages into a signal through a reducer. This is the same pattern as the WebSocket module:

import { sse, signal } from 'tina4js';

const messages = signal([]);

const stream = sse.connect('/api/notifications');
stream.pipe(messages, (msg, current) => [...current, msg]);

// messages.value grows as notifications arrive
effect(() => {
  console.log(`${messages.value.length} notifications`);
});

Pipe returns an unsubscribe function:

const unsub = stream.pipe(messages, (msg, current) => [...current, msg]);

// Stop piping
unsub();

---

9. Auto-Reconnect

In EventSource mode, the browser handles reconnection natively. If the connection is fully closed, tina4-js schedules manual reconnection with exponential backoff.

In fetch mode, tina4-js handles all reconnection:

const stream = sse.connect('/api/stream', {
  mode: 'fetch',
  reconnect: true,
  reconnectDelay: 1000,       // Start at 1s
  reconnectMaxDelay: 30000,   // Cap at 30s
  reconnectAttempts: 10,      // Give up after 10 tries
});

effect(() => {
  if (stream.status.value === 'reconnecting') {
    console.log(`Reconnect attempt ${stream.reconnectCount.value}`);
  }
});

---

10. Closing

stream.close();

This stops the connection and prevents reconnection. In EventSource mode it calls source.close(). In fetch mode it aborts the fetch request.

---

11. SSE vs WebSocket

	SSE	WebSocket
Direction	Server → Client	Bidirectional
Protocol	HTTP	WS/WSS
Reconnect	Built-in (EventSource)	Manual (tina4-js handles it)
Headers	No (EventSource) / Yes (fetch mode)	Subprotocols only
POST body	No (EventSource) / Yes (fetch mode)	N/A
Binary data	No	Yes
HTTP/2 multiplexing	Yes	No
Use case	Notifications, feeds, AI streaming	Chat, gaming, live collaboration

Rule of thumb: If the client only needs to receive, use SSE. If the client needs to send too, use WebSocket.

---

12. Real-World Example: AI Chat Streaming

import { sse, signal, html } from 'tina4js';

const messages = signal([]);
const input = signal('');
const streaming = signal(false);

async function sendMessage() {
  const prompt = input.value.trim();
  if (!prompt) return;

  // Add user message
  messages.value = [...messages.value, { role: 'user', text: prompt }];
  input.value = '';

  // Add empty assistant message
  messages.value = [...messages.value, { role: 'assistant', text: '' }];
  streaming.value = true;

  // Stream tokens
  const stream = sse.connect('/api/chat', {
    mode: 'fetch',
    method: 'POST',
    headers: { 'Authorization': `Bearer ${localStorage.getItem('token')}` },
    body: { prompt },
  });

  stream.on('message', (data) => {
    const token = data.token || data;
    const msgs = [...messages.value];
    const last = msgs[msgs.length - 1];
    msgs[msgs.length - 1] = { ...last, text: last.text + token };
    messages.value = msgs;
  });

  stream.on('close', () => {
    streaming.value = false;
  });
}

const view = html`
  <div class="chat">
    ${() => messages.value.map(m => html`
      <div class="message ${m.role}">
        <strong>${m.role}:</strong> ${m.text}
      </div>
    `)}
    <div class="input-bar">
      <input
        type="text"
        .value=${input}
        @input=${(e) => { input.value = e.target.value; }}
        @keydown=${(e) => { if (e.key === 'Enter') sendMessage(); }}
        ?disabled=${streaming}
      />
      <button @click=${sendMessage} ?disabled=${streaming}>Send</button>
    </div>
  </div>
`;

---

13. Real-World Example: Live Notification Feed

import { sse, signal, html } from 'tina4js';

const notifications = signal([]);

const stream = sse.connect('/api/notifications', {
  events: ['info', 'warning', 'error'],
});

stream.pipe(notifications, (msg, current) => {
  return [{ ...msg, event: stream.lastEvent.value, time: new Date() }, ...current].slice(0, 50);
});

const view = html`
  <div class="feed">
    <h2>Notifications ${() => stream.connected.value ? '(live)' : '(disconnected)'}</h2>
    ${() => notifications.value.map(n => html`
      <div class="notification ${n.event}">
        <span class="badge">${n.event}</span>
        ${n.message}
        <small>${n.time.toLocaleTimeString()}</small>
      </div>
    `)}
  </div>
`;

---

Bundle Size

Module	Raw	Gzipped
SSE	3.42 KB	1.30 KB

Import only what you need:

import { sse } from 'tina4js/sse';  // 1.30 KB gzip

---

Summary

Task	Code
Connect (EventSource)	sse.connect('/events')
Connect (NDJSON/POST)	sse.connect('/api', { mode: 'fetch', method: 'POST', body: {...} })
Read status	stream.status.value
Listen for messages	stream.on('message', (data, event?) => { ... })
Named events	sse.connect(url, { events: ['update', 'delete'] })
Pipe to signal	stream.pipe(signal, (msg, current) => [...current, msg])
Close	stream.close()