@mooncompany/uplink-chat 0.5.0

package/public/js/utils/sse-parser.js

@@ -0,0 +1,195 @@
+// ============================================
+// SSE PARSER UTILITY
+// Server-Sent Events stream parsing
+// ============================================
+//
+// NOTE: The primary SSE handling for chat streaming is in streaming-handler.js
+// (UplinkStreamingHandler). This utility provides a standalone parser
+// for use by modules that need SSE parsing without the full streaming handler
+// (e.g., image uploads, file uploads, standalone API calls).
+//
+
+/**
+ * SSE Parser class for handling Server-Sent Events streams.
+ * Handles buffering, line parsing, and JSON decoding.
+ */
+export class SSEParser {
+  constructor() {
+    this.buffer = '';
+    this.decoder = new TextDecoder();
+  }
+
+  /**
+   * Reset the parser state.
+   */
+  reset() {
+    this.buffer = '';
+  }
+
+  /**
+   * Process a chunk of data and return parsed events.
+   *
+   * @param {Uint8Array} chunk - The raw chunk from the stream
+   * @returns {Array<Object>} Array of parsed event objects
+   */
+  processChunk(chunk) {
+    const events = [];
+
+    // Decode and append to buffer
+    this.buffer += this.decoder.decode(chunk, { stream: true });
+
+    // Split into lines, keeping incomplete line in buffer
+    const lines = this.buffer.split('\n');
+    this.buffer = lines.pop() || '';
+
+    for (const line of lines) {
+      const event = this.parseLine(line);
+      if (event !== null) {
+        events.push(event);
+      }
+    }
+
+    return events;
+  }
+
+  /**
+   * Parse a single SSE line.
+   *
+   * @param {string} line - The line to parse
+   * @returns {Object|null} Parsed event or null
+   */
+  parseLine(line) {
+    // Skip empty lines
+    if (!line.trim()) {
+      return null;
+    }
+
+    // Skip SSE comments/keepalives
+    if (line.startsWith(':')) {
+      return null;
+    }
+
+    // Must be a data line
+    if (!line.startsWith('data: ')) {
+      return null;
+    }
+
+    const data = line.slice(6); // Remove 'data: ' prefix
+
+    // Handle stream completion
+    if (data === '[DONE]') {
+      return { type: 'done' };
+    }
+
+    // Try to parse as JSON
+    try {
+      const parsed = JSON.parse(data);
+      return { type: 'data', payload: parsed };
+    } catch (e) {
+      // Return raw data if not valid JSON
+      return { type: 'raw', data };
+    }
+  }
+
+  /**
+   * Flush any remaining data in the buffer.
+   * Call this when the stream ends.
+   *
+   * @returns {Object|null} Final parsed event or null
+   */
+  flush() {
+    if (this.buffer.trim()) {
+      const result = this.parseLine(this.buffer);
+      this.buffer = '';
+      return result;
+    }
+    return null;
+  }
+}
+
+/**
+ * Dispatch a single parsed event to the appropriate handler.
+ */
+function handleEvent(event, handlers) {
+  switch (event.type) {
+    case 'data':
+      handlers.onData?.(event.payload);
+      break;
+    case 'done':
+      handlers.onDone?.();
+      break;
+    case 'raw':
+      handlers.onRaw?.(event.data);
+      break;
+  }
+}
+
+/**
+ * Process an SSE stream from a fetch response with callbacks.
+ *
+ * @param {Response} response - Fetch response with SSE body
+ * @param {Object} handlers - Event handlers
+ * @param {Function} [handlers.onData] - Called for each parsed data event (receives payload)
+ * @param {Function} [handlers.onDone] - Called when stream completes
+ * @param {Function} [handlers.onError] - Called on errors
+ * @param {Function} [handlers.onRaw] - Called for unparseable raw data
+ * @param {AbortSignal} [signal] - Optional abort signal
+ *
+ * @example
+ * await UplinkSSEParser.processStream(response, {
+ *   onData: (payload) => console.log(payload),
+ *   onDone: () => console.log('Done'),
+ *   onError: (err) => console.error(err)
+ * });
+ */
+export async function processStream(response, handlers, signal) {
+  const { onData, onDone, onError, onRaw } = handlers;
+  const parser = new SSEParser();
+  const reader = response.body.getReader();
+
+  try {
+    while (true) {
+      if (signal?.aborted) break;
+
+      const { done, value } = await reader.read();
+
+      if (done) {
+        const finalEvent = parser.flush();
+        if (finalEvent) {
+          handleEvent(finalEvent, { onData, onDone, onRaw });
+        }
+        onDone?.();
+        break;
+      }
+
+      const events = parser.processChunk(value);
+      for (const event of events) {
+        handleEvent(event, { onData, onDone, onRaw });
+      }
+    }
+  } catch (err) {
+    if (err.name === 'AbortError') {
+      onDone?.();
+    } else {
+      onError?.(err);
+    }
+  } finally {
+    reader.releaseLock();
+  }
+}
+
+// ============================================
+// PUBLIC API
+// ============================================
+
+export const UplinkSSEParser = {
+  SSEParser,
+  processStream
+};
+
+// Backward compat: assign to window
+window.UplinkSSEParser = UplinkSSEParser;
+
+if (typeof logger !== 'undefined') {
+  logger.debug('SSEParser: Module loaded');
+}