@durable-streams/client 0.1.5 → 0.2.1

package/src/response.ts

@@ -7,6 +7,7 @@
 
 import { asAsyncIterableReadableStream } from "./asyncIterableReadableStream"
 import {
+  STREAM_CLOSED_HEADER,
   STREAM_CURSOR_HEADER,
   STREAM_OFFSET_HEADER,
   STREAM_UP_TO_DATE_HEADER,
@@ -55,6 +56,8 @@ export interface StreamResponseConfig {
   initialCursor?: string
   /** Initial upToDate from first response headers */
   initialUpToDate: boolean
+  /** Initial streamClosed from first response headers */
+  initialStreamClosed: boolean
   /** The held first Response object */
   firstResponse: Response
   /** Abort controller for the session */
@@ -74,6 +77,8 @@ export interface StreamResponseConfig {
   ) => Promise<Response>
   /** SSE resilience options */
   sseResilience?: SSEResilienceOptions
+  /** Encoding for SSE data events */
+  encoding?: `base64`
 }
 
 /**
@@ -96,9 +101,10 @@ export class StreamResponseImpl<
   #isLoading: boolean
 
   // --- Evolving state ---
-  offset: Offset
-  cursor?: string
-  upToDate: boolean
+  #offset: Offset
+  #cursor?: string
+  #upToDate: boolean
+  #streamClosed: boolean
 
   // --- Internal state ---
   #isJsonMode: boolean
@@ -125,6 +131,9 @@ export class StreamResponseImpl<
   #consecutiveShortSSEConnections = 0
   #sseFallbackToLongPoll = false
 
+  // --- SSE Encoding State ---
+  #encoding?: `base64`
+
   // Core primitive: a ReadableStream of Response objects
   #responseStream: ReadableStream<Response>
 
@@ -133,9 +142,10 @@ export class StreamResponseImpl<
     this.contentType = config.contentType
     this.live = config.live
     this.startOffset = config.startOffset
-    this.offset = config.initialOffset
-    this.cursor = config.initialCursor
-    this.upToDate = config.initialUpToDate
+    this.#offset = config.initialOffset
+    this.#cursor = config.initialCursor
+    this.#upToDate = config.initialUpToDate
+    this.#streamClosed = config.initialStreamClosed
 
     // Initialize response metadata from first response
     this.#headers = config.firstResponse.headers
@@ -162,6 +172,9 @@ export class StreamResponseImpl<
       logWarnings: config.sseResilience?.logWarnings ?? true,
     }
 
+    // Initialize SSE encoding
+    this.#encoding = config.encoding
+
     this.#closed = new Promise((resolve, reject) => {
       this.#closedResolve = resolve
       this.#closedReject = reject
@@ -284,6 +297,24 @@ export class StreamResponseImpl<
     return this.#isLoading
   }
 
+  // --- Evolving state getters ---
+
+  get offset(): Offset {
+    return this.#offset
+  }
+
+  get cursor(): string | undefined {
+    return this.#cursor
+  }
+
+  get upToDate(): boolean {
+    return this.#upToDate
+  }
+
+  get streamClosed(): boolean {
+    return this.#streamClosed
+  }
+
   // =================================
   // Internal helpers
   // =================================
@@ -324,13 +355,15 @@ export class StreamResponseImpl<
 
   /**
    * Determine if we should continue with live updates based on live mode
-   * and whether we've received upToDate.
+   * and whether we've received upToDate or streamClosed.
    */
   #shouldContinueLive(): boolean {
     // Stop if we've received upToDate and a consumption method wants to stop after upToDate
     if (this.#stopAfterUpToDate && this.upToDate) return false
     // Stop if live mode is explicitly disabled
     if (this.live === false) return false
+    // Stop if stream is closed (EOF) - no more data will ever be appended
+    if (this.#streamClosed) return false
     return true
   }
 
@@ -340,10 +373,14 @@ export class StreamResponseImpl<
   #updateStateFromResponse(response: Response): void {
     // Update stream-specific state
     const offset = response.headers.get(STREAM_OFFSET_HEADER)
-    if (offset) this.offset = offset
+    if (offset) this.#offset = offset
     const cursor = response.headers.get(STREAM_CURSOR_HEADER)
-    if (cursor) this.cursor = cursor
-    this.upToDate = response.headers.has(STREAM_UP_TO_DATE_HEADER)
+    if (cursor) this.#cursor = cursor
+    this.#upToDate = response.headers.has(STREAM_UP_TO_DATE_HEADER)
+    const streamClosedHeader = response.headers.get(STREAM_CLOSED_HEADER)
+    if (streamClosedHeader?.toLowerCase() === `true`) {
+      this.#streamClosed = true
+    }
 
     // Update response metadata to reflect latest server response
     this.#headers = response.headers
@@ -354,7 +391,7 @@ export class StreamResponseImpl<
 
   /**
    * Extract stream metadata from Response headers.
-   * Used by subscriber APIs to get the correct offset/cursor/upToDate for each
+   * Used by subscriber APIs to get the correct offset/cursor/upToDate/streamClosed for each
    * specific Response, rather than reading from `this` which may be stale due to
    * ReadableStream prefetching or timing issues.
    */
@@ -362,26 +399,94 @@ export class StreamResponseImpl<
     offset: Offset
     cursor: string | undefined
     upToDate: boolean
+    streamClosed: boolean
   } {
     const offset = response.headers.get(STREAM_OFFSET_HEADER)
     const cursor = response.headers.get(STREAM_CURSOR_HEADER)
     const upToDate = response.headers.has(STREAM_UP_TO_DATE_HEADER)
+    const streamClosed =
+      response.headers.get(STREAM_CLOSED_HEADER)?.toLowerCase() === `true`
     return {
       offset: offset ?? this.offset, // Fall back to instance state if no header
       cursor: cursor ?? this.cursor,
       upToDate,
+      streamClosed: streamClosed || this.streamClosed, // Once closed, always closed
+    }
+  }
+
+  /**
+   * Decode base64 string to Uint8Array.
+   * Per protocol: concatenate data lines, remove \n and \r, then decode.
+   */
+  #decodeBase64(base64Str: string): Uint8Array {
+    // Remove all newlines and carriage returns per protocol
+    const cleaned = base64Str.replace(/[\n\r]/g, ``)
+
+    // Empty string is valid
+    if (cleaned.length === 0) {
+      return new Uint8Array(0)
+    }
+
+    // Validate length is multiple of 4
+    if (cleaned.length % 4 !== 0) {
+      throw new DurableStreamError(
+        `Invalid base64 data: length ${cleaned.length} is not a multiple of 4`,
+        `PARSE_ERROR`
+      )
+    }
+
+    try {
+      // Prefer Buffer (native C++ in Node) over atob (requires JS charCodeAt loop)
+      if (typeof Buffer !== `undefined`) {
+        return new Uint8Array(Buffer.from(cleaned, `base64`))
+      } else {
+        const binaryStr = atob(cleaned)
+        const bytes = new Uint8Array(binaryStr.length)
+        for (let i = 0; i < binaryStr.length; i++) {
+          bytes[i] = binaryStr.charCodeAt(i)
+        }
+        return bytes
+      }
+    } catch (err) {
+      throw new DurableStreamError(
+        `Failed to decode base64 data: ${err instanceof Error ? err.message : String(err)}`,
+        `PARSE_ERROR`
+      )
     }
   }
 
   /**
    * Create a synthetic Response from SSE data with proper headers.
-   * Includes offset/cursor/upToDate in headers so subscribers can read them.
+   * Includes offset/cursor/upToDate/streamClosed in headers so subscribers can read them.
    */
   #createSSESyntheticResponse(
     data: string,
     offset: Offset,
     cursor: string | undefined,
-    upToDate: boolean
+    upToDate: boolean,
+    streamClosed: boolean
+  ): Response {
+    return this.#createSSESyntheticResponseFromParts(
+      [data],
+      offset,
+      cursor,
+      upToDate,
+      streamClosed
+    )
+  }
+
+  /**
+   * Create a synthetic Response from multiple SSE data parts.
+   * For base64 mode, each part is independently encoded, so we decode each
+   * separately and concatenate the binary results.
+   * For text mode, parts are simply concatenated as strings.
+   */
+  #createSSESyntheticResponseFromParts(
+    dataParts: Array<string>,
+    offset: Offset,
+    cursor: string | undefined,
+    upToDate: boolean,
+    streamClosed: boolean
   ): Response {
     const headers: Record<string, string> = {
       "content-type": this.contentType ?? `application/json`,
@@ -393,19 +498,64 @@ export class StreamResponseImpl<
     if (upToDate) {
       headers[STREAM_UP_TO_DATE_HEADER] = `true`
     }
-    return new Response(data, { status: 200, headers })
+    if (streamClosed) {
+      headers[STREAM_CLOSED_HEADER] = `true`
+    }
+
+    // Decode base64 if encoding is used
+    let body: BodyInit
+    if (this.#encoding === `base64`) {
+      // Each data part is independently base64 encoded, decode each separately
+      const decodedParts = dataParts
+        .filter((part) => part.length > 0)
+        .map((part) => this.#decodeBase64(part))
+
+      if (decodedParts.length === 0) {
+        // No data - return empty body
+        body = new ArrayBuffer(0)
+      } else if (decodedParts.length === 1) {
+        // Single part - use directly
+        const decoded = decodedParts[0]!
+        body = decoded.buffer.slice(
+          decoded.byteOffset,
+          decoded.byteOffset + decoded.byteLength
+        ) as ArrayBuffer
+      } else {
+        // Multiple parts - concatenate binary data
+        const totalLength = decodedParts.reduce(
+          (sum, part) => sum + part.length,
+          0
+        )
+        const combined = new Uint8Array(totalLength)
+        let offset = 0
+        for (const part of decodedParts) {
+          combined.set(part, offset)
+          offset += part.length
+        }
+        body = combined.buffer
+      }
+    } else {
+      body = dataParts.join(``)
+    }
+
+    return new Response(body, { status: 200, headers })
   }
 
   /**
    * Update instance state from an SSE control event.
    */
   #updateStateFromSSEControl(controlEvent: SSEControlEvent): void {
-    this.offset = controlEvent.streamNextOffset
+    this.#offset = controlEvent.streamNextOffset
     if (controlEvent.streamCursor) {
-      this.cursor = controlEvent.streamCursor
+      this.#cursor = controlEvent.streamCursor
     }
     if (controlEvent.upToDate !== undefined) {
-      this.upToDate = controlEvent.upToDate
+      this.#upToDate = controlEvent.upToDate
+    }
+    if (controlEvent.streamClosed) {
+      this.#streamClosed = true
+      // A closed stream is definitionally up-to-date - no more data will ever be appended
+      this.#upToDate = true
     }
   }
 
@@ -564,8 +714,22 @@ export class StreamResponseImpl<
       return this.#processSSEDataEvent(event.data, sseEventIterator)
     }
 
-    // Control event without preceding data - update state and continue
+    // Control event without preceding data - update state
     this.#updateStateFromSSEControl(event)
+
+    // If upToDate is signaled, yield an empty response so subscribers receive the signal
+    // This is important for empty streams and for subscribers waiting for catch-up completion
+    if (event.upToDate) {
+      const response = this.#createSSESyntheticResponse(
+        ``,
+        event.streamNextOffset,
+        event.streamCursor,
+        true,
+        event.streamClosed ?? false
+      )
+      return { type: `response`, response }
+    }
+
     return { type: `continue` }
   }
 
@@ -573,6 +737,9 @@ export class StreamResponseImpl<
    * Process an SSE data event by waiting for its corresponding control event.
    * In SSE protocol, control events come AFTER data events.
    * Multiple data events may arrive before a single control event - we buffer them.
+   *
+   * For base64 mode, each data event is independently base64 encoded, so we
+   * collect them as an array and decode each separately.
    */
   async #processSSEDataEvent(
     pendingData: string,
@@ -586,7 +753,8 @@ export class StreamResponseImpl<
     | { type: `error`; error: Error }
   > {
     // Buffer to accumulate data from multiple consecutive data events
-    let bufferedData = pendingData
+    // For base64 mode, we collect as array since each event is independently encoded
+    const bufferedDataParts: Array<string> = [pendingData]
 
     // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
     while (true) {
@@ -595,11 +763,12 @@ export class StreamResponseImpl<
 
       if (controlDone) {
         // Stream ended without control event - yield buffered data with current state
-        const response = this.#createSSESyntheticResponse(
-          bufferedData,
+        const response = this.#createSSESyntheticResponseFromParts(
+          bufferedDataParts,
           this.offset,
           this.cursor,
-          this.upToDate
+          this.upToDate,
+          this.streamClosed
         )
 
         // Try to reconnect
@@ -622,18 +791,19 @@ export class StreamResponseImpl<
       if (controlEvent.type === `control`) {
         // Update state and create response with correct metadata
         this.#updateStateFromSSEControl(controlEvent)
-        const response = this.#createSSESyntheticResponse(
-          bufferedData,
+        const response = this.#createSSESyntheticResponseFromParts(
+          bufferedDataParts,
           controlEvent.streamNextOffset,
           controlEvent.streamCursor,
-          controlEvent.upToDate ?? false
+          controlEvent.upToDate ?? false,
+          controlEvent.streamClosed ?? false
         )
         return { type: `response`, response }
       }
 
       // Got another data event before control - buffer it
       // Server sends multiple data events followed by one control event
-      bufferedData += controlEvent.data
+      bufferedDataParts.push(controlEvent.data)
     }
   }
 
@@ -887,7 +1057,17 @@ export class StreamResponseImpl<
         // Get response text first (handles empty responses gracefully)
         const text = await result.value.text()
         const content = text.trim() || `[]` // Default to empty array if no content or whitespace
-        const parsed = JSON.parse(content) as T | Array<T>
+        let parsed: T | Array<T>
+        try {
+          parsed = JSON.parse(content) as T | Array<T>
+        } catch (err) {
+          const preview =
+            content.length > 100 ? content.slice(0, 100) + `...` : content
+          throw new DurableStreamError(
+            `Failed to parse JSON response: ${err instanceof Error ? err.message : String(err)}. Data: ${preview}`,
+            `PARSE_ERROR`
+          )
+        }
         if (Array.isArray(parsed)) {
           items.push(...parsed)
         } else {
@@ -1021,7 +1201,17 @@ export class StreamResponseImpl<
         // Parse JSON and flatten arrays (handle empty responses gracefully)
         const text = await response.text()
         const content = text.trim() || `[]` // Default to empty array if no content or whitespace
-        const parsed = JSON.parse(content) as TJson | Array<TJson>
+        let parsed: TJson | Array<TJson>
+        try {
+          parsed = JSON.parse(content) as TJson | Array<TJson>
+        } catch (err) {
+          const preview =
+            content.length > 100 ? content.slice(0, 100) + `...` : content
+          throw new DurableStreamError(
+            `Failed to parse JSON response: ${err instanceof Error ? err.message : String(err)}. Data: ${preview}`,
+            `PARSE_ERROR`
+          )
+        }
         pendingItems = Array.isArray(parsed) ? parsed : [parsed]
 
         // Enqueue first item
@@ -1065,7 +1255,7 @@ export class StreamResponseImpl<
   // =====================
 
   subscribeJson<T = TJson>(
-    subscriber: (batch: JsonBatch<T>) => Promise<void>
+    subscriber: (batch: JsonBatch<T>) => void | Promise<void>
   ): () => void {
     this.#ensureNoConsumption(`subscribeJson`)
     this.#ensureJsonMode()
@@ -1080,20 +1270,32 @@ export class StreamResponseImpl<
 
           // Get metadata from Response headers (not from `this` which may be stale)
           const response = result.value
-          const { offset, cursor, upToDate } =
+          const { offset, cursor, upToDate, streamClosed } =
             this.#getMetadataFromResponse(response)
 
           // Get response text first (handles empty responses gracefully)
           const text = await response.text()
           const content = text.trim() || `[]` // Default to empty array if no content or whitespace
-          const parsed = JSON.parse(content) as T | Array<T>
+          let parsed: T | Array<T>
+          try {
+            parsed = JSON.parse(content) as T | Array<T>
+          } catch (err) {
+            const preview =
+              content.length > 100 ? content.slice(0, 100) + `...` : content
+            throw new DurableStreamError(
+              `Failed to parse JSON response: ${err instanceof Error ? err.message : String(err)}. Data: ${preview}`,
+              `PARSE_ERROR`
+            )
+          }
           const items = Array.isArray(parsed) ? parsed : [parsed]
 
+          // Await callback (handles both sync and async)
           await subscriber({
             items,
             offset,
             cursor,
             upToDate,
+            streamClosed,
           })
 
           result = await reader.read()
@@ -1121,7 +1323,9 @@ export class StreamResponseImpl<
     }
   }
 
-  subscribeBytes(subscriber: (chunk: ByteChunk) => Promise<void>): () => void {
+  subscribeBytes(
+    subscriber: (chunk: ByteChunk) => void | Promise<void>
+  ): () => void {
     this.#ensureNoConsumption(`subscribeBytes`)
     const abortController = new AbortController()
     const reader = this.#getResponseReader()
@@ -1134,16 +1338,18 @@ export class StreamResponseImpl<
 
           // Get metadata from Response headers (not from `this` which may be stale)
           const response = result.value
-          const { offset, cursor, upToDate } =
+          const { offset, cursor, upToDate, streamClosed } =
             this.#getMetadataFromResponse(response)
 
           const buffer = await response.arrayBuffer()
 
+          // Await callback (handles both sync and async)
           await subscriber({
             data: new Uint8Array(buffer),
             offset,
             cursor,
             upToDate,
+            streamClosed,
           })
 
           result = await reader.read()
@@ -1171,7 +1377,9 @@ export class StreamResponseImpl<
     }
   }
 
-  subscribeText(subscriber: (chunk: TextChunk) => Promise<void>): () => void {
+  subscribeText(
+    subscriber: (chunk: TextChunk) => void | Promise<void>
+  ): () => void {
     this.#ensureNoConsumption(`subscribeText`)
     const abortController = new AbortController()
     const reader = this.#getResponseReader()
@@ -1184,16 +1392,18 @@ export class StreamResponseImpl<
 
           // Get metadata from Response headers (not from `this` which may be stale)
           const response = result.value
-          const { offset, cursor, upToDate } =
+          const { offset, cursor, upToDate, streamClosed } =
             this.#getMetadataFromResponse(response)
 
           const text = await response.text()
 
+          // Await callback (handles both sync and async)
           await subscriber({
             text,
             offset,
             cursor,
             upToDate,
+            streamClosed,
           })
 
           result = await reader.read()

package/src/sse.ts

@@ -6,6 +6,7 @@
  * - `event: control` events contain `streamNextOffset` and optional `streamCursor` and `upToDate`
  */
 
+import { DurableStreamError } from "./error"
 import type { Offset } from "./types"
 
 /**
@@ -21,6 +22,7 @@ export interface SSEControlEvent {
   streamNextOffset: Offset
   streamCursor?: string
   upToDate?: boolean
+  streamClosed?: boolean
 }
 
 export type SSEEvent = SSEDataEvent | SSEControlEvent
@@ -72,21 +74,34 @@ export async function* parseSSEStream(
                   streamNextOffset: Offset
                   streamCursor?: string
                   upToDate?: boolean
+                  streamClosed?: boolean
                 }
                 yield {
                   type: `control`,
                   streamNextOffset: control.streamNextOffset,
                   streamCursor: control.streamCursor,
                   upToDate: control.upToDate,
+                  streamClosed: control.streamClosed,
                 }
-              } catch {
-                // Invalid control event, skip
+              } catch (err) {
+                // Control events contain critical offset data - don't silently ignore
+                const preview =
+                  dataStr.length > 100 ? dataStr.slice(0, 100) + `...` : dataStr
+                throw new DurableStreamError(
+                  `Failed to parse SSE control event: ${err instanceof Error ? err.message : String(err)}. Data: ${preview}`,
+                  `PARSE_ERROR`
+                )
               }
             }
+            // Unknown event types are silently skipped per protocol
           }
           currentEvent = { data: [] }
         } else if (line.startsWith(`event:`)) {
-          currentEvent.type = line.slice(6).trim()
+          // Per SSE spec, strip only one optional space after "event:"
+          const eventType = line.slice(6)
+          currentEvent.type = eventType.startsWith(` `)
+            ? eventType.slice(1)
+            : eventType
         } else if (line.startsWith(`data:`)) {
           // Per SSE spec, strip the optional space after "data:"
           const content = line.slice(5)
@@ -115,15 +130,22 @@ export async function* parseSSEStream(
             streamNextOffset: Offset
             streamCursor?: string
             upToDate?: boolean
+            streamClosed?: boolean
           }
           yield {
             type: `control`,
             streamNextOffset: control.streamNextOffset,
             streamCursor: control.streamCursor,
             upToDate: control.upToDate,
+            streamClosed: control.streamClosed,
           }
-        } catch {
-          // Invalid control event, skip
+        } catch (err) {
+          const preview =
+            dataStr.length > 100 ? dataStr.slice(0, 100) + `...` : dataStr
+          throw new DurableStreamError(
+            `Failed to parse SSE control event: ${err instanceof Error ? err.message : String(err)}. Data: ${preview}`,
+            `PARSE_ERROR`
+          )
         }
       }
     }