@durable-streams/client 0.1.4 → 0.2.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@durable-streams/client",
   "description": "TypeScript client for the Durable Streams protocol",
-  "version": "0.1.4",
+  "version": "0.2.0",
   "author": "Durable Stream contributors",
   "license": "Apache-2.0",
   "repository": {
@@ -47,7 +47,7 @@
   "devDependencies": {
     "fast-check": "^4.4.0",
     "tsdown": "^0.9.0",
-    "@durable-streams/server": "0.1.5"
+    "@durable-streams/server": "0.1.7"
   },
   "engines": {
     "node": ">=18.0.0"

package/src/idempotent-producer.ts

@@ -76,12 +76,9 @@ function normalizeContentType(contentType: string | undefined): string {
 
 /**
  * Internal type for pending batch entries.
- * Stores original data for proper JSON batching.
  */
 interface PendingEntry {
-  /** Original data - parsed for JSON mode batching */
-  data: unknown
-  /** Encoded bytes for byte-stream mode */
+  /** Encoded bytes */
   body: Uint8Array
 }
 
@@ -173,18 +170,37 @@ export class IdempotentProducer {
     producerId: string,
     opts?: IdempotentProducerOptions
   ) {
+    // Validate inputs
+    const epoch = opts?.epoch ?? 0
+    const maxBatchBytes = opts?.maxBatchBytes ?? 1024 * 1024 // 1MB
+    const maxInFlight = opts?.maxInFlight ?? 5
+    const lingerMs = opts?.lingerMs ?? 5
+
+    if (epoch < 0) {
+      throw new Error(`epoch must be >= 0`)
+    }
+    if (maxBatchBytes <= 0) {
+      throw new Error(`maxBatchBytes must be > 0`)
+    }
+    if (maxInFlight <= 0) {
+      throw new Error(`maxInFlight must be > 0`)
+    }
+    if (lingerMs < 0) {
+      throw new Error(`lingerMs must be >= 0`)
+    }
+
     this.#stream = stream
     this.#producerId = producerId
-    this.#epoch = opts?.epoch ?? 0
+    this.#epoch = epoch
     this.#autoClaim = opts?.autoClaim ?? false
-    this.#maxBatchBytes = opts?.maxBatchBytes ?? 1024 * 1024 // 1MB
-    this.#lingerMs = opts?.lingerMs ?? 5
+    this.#maxBatchBytes = maxBatchBytes
+    this.#lingerMs = lingerMs
     this.#signal = opts?.signal
     this.#onError = opts?.onError
     this.#fetchClient =
       opts?.fetch ?? ((...args: Parameters<typeof fetch>) => fetch(...args))
 
-    this.#maxInFlight = opts?.maxInFlight ?? 5
+    this.#maxInFlight = maxInFlight
 
     // When autoClaim is true, epoch is not yet known until first batch completes
     // We block pipelining until then to avoid racing with the claim
@@ -224,12 +240,22 @@ export class IdempotentProducer {
    * Errors are reported via onError callback if configured. Use flush() to
    * wait for all pending messages to be sent.
    *
-   * For JSON streams, pass native objects (which will be serialized internally).
+   * For JSON streams, pass pre-serialized JSON strings.
    * For byte streams, pass string or Uint8Array.
    *
-   * @param body - Data to append (object for JSON streams, string or Uint8Array for byte streams)
+   * @param body - Data to append (string or Uint8Array)
+   *
+   * @example
+   * ```typescript
+   * // JSON stream
+   * producer.append(JSON.stringify({ message: "hello" }));
+   *
+   * // Byte stream
+   * producer.append("raw text data");
+   * producer.append(new Uint8Array([1, 2, 3]));
+   * ```
    */
-  append(body: Uint8Array | string | unknown): void {
+  append(body: Uint8Array | string): void {
     if (this.#closed) {
       throw new DurableStreamError(
         `Producer is closed`,
@@ -239,35 +265,21 @@ export class IdempotentProducer {
       )
     }
 
-    const isJson =
-      normalizeContentType(this.#stream.contentType) === `application/json`
-
     let bytes: Uint8Array
-    let data: unknown
-
-    if (isJson) {
-      // For JSON streams: accept native objects, serialize internally
-      const json = JSON.stringify(body)
-      bytes = new TextEncoder().encode(json)
-      data = body
+    if (typeof body === `string`) {
+      bytes = new TextEncoder().encode(body)
+    } else if (body instanceof Uint8Array) {
+      bytes = body
     } else {
-      // For byte streams, require string or Uint8Array
-      if (typeof body === `string`) {
-        bytes = new TextEncoder().encode(body)
-      } else if (body instanceof Uint8Array) {
-        bytes = body
-      } else {
-        throw new DurableStreamError(
-          `Non-JSON streams require string or Uint8Array`,
-          `BAD_REQUEST`,
-          400,
-          undefined
-        )
-      }
-      data = bytes
+      throw new DurableStreamError(
+        `append() requires string or Uint8Array. For objects, use JSON.stringify().`,
+        `BAD_REQUEST`,
+        400,
+        undefined
+      )
     }
 
-    this.#pendingBatch.push({ data, body: bytes })
+    this.#pendingBatch.push({ body: bytes })
     this.#batchBytes += bytes.length
 
     // Check if batch should be sent immediately
@@ -523,8 +535,9 @@ export class IdempotentProducer {
       // For JSON mode: always send as array (server flattens one level)
       // Single append: [value] → server stores value
       // Multiple appends: [val1, val2] → server stores val1, val2
-      const values = batch.map((e) => e.data)
-      batchedBody = JSON.stringify(values)
+      // Input is pre-serialized JSON strings, join them into an array
+      const jsonStrings = batch.map((e) => new TextDecoder().decode(e.body))
+      batchedBody = `[${jsonStrings.join(`,`)}]`
     } else {
       // For byte mode: concatenate all chunks
       const totalSize = batch.reduce((sum, e) => sum + e.body.length, 0)

package/src/response.ts

@@ -25,6 +25,16 @@ import type {
   TextChunk,
 } from "./types"
 
+/**
+ * Constant used as abort reason when pausing the stream due to visibility change.
+ */
+const PAUSE_STREAM = `PAUSE_STREAM`
+
+/**
+ * State machine for visibility-based pause/resume.
+ */
+type StreamState = `active` | `pause-requested` | `paused`
+
 /**
  * Internal configuration for creating a StreamResponse.
  */
@@ -53,7 +63,8 @@ export interface StreamResponseConfig {
   fetchNext: (
     offset: Offset,
     cursor: string | undefined,
-    signal: AbortSignal
+    signal: AbortSignal,
+    resumingFromPause?: boolean
   ) => Promise<Response>
   /** Function to start SSE connection and return a Response with SSE body */
   startSSE?: (
@@ -85,9 +96,9 @@ export class StreamResponseImpl<
   #isLoading: boolean
 
   // --- Evolving state ---
-  offset: Offset
-  cursor?: string
-  upToDate: boolean
+  #offset: Offset
+  #cursor?: string
+  #upToDate: boolean
 
   // --- Internal state ---
   #isJsonMode: boolean
@@ -100,6 +111,14 @@ export class StreamResponseImpl<
   #stopAfterUpToDate = false
   #consumptionMethod: string | null = null
 
+  // --- Visibility/Pause State ---
+  #state: StreamState = `active`
+  #requestAbortController?: AbortController
+  #unsubscribeFromVisibilityChanges?: () => void
+  #pausePromise?: Promise<void>
+  #pauseResolve?: () => void
+  #justResumedFromPause = false
+
   // --- SSE Resilience State ---
   #sseResilience: Required<SSEResilienceOptions>
   #lastSSEConnectionStartTime?: number
@@ -114,9 +133,9 @@ 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
 
     // Initialize response metadata from first response
     this.#headers = config.firstResponse.headers
@@ -150,6 +169,97 @@ export class StreamResponseImpl<
 
     // Create the core response stream
     this.#responseStream = this.#createResponseStream(config.firstResponse)
+
+    // Install single abort listener that propagates to current request controller
+    // and unblocks any paused pull() (avoids accumulating one listener per request)
+    this.#abortController.signal.addEventListener(
+      `abort`,
+      () => {
+        this.#requestAbortController?.abort(this.#abortController.signal.reason)
+        // Unblock pull() if paused, so it can see the abort and close
+        this.#pauseResolve?.()
+        this.#pausePromise = undefined
+        this.#pauseResolve = undefined
+      },
+      { once: true }
+    )
+
+    // Subscribe to visibility changes for pause/resume (browser only)
+    this.#subscribeToVisibilityChanges()
+  }
+
+  /**
+   * Subscribe to document visibility changes to pause/resume syncing.
+   * When the page is hidden, we pause to save battery and bandwidth.
+   * When visible again, we resume syncing.
+   */
+  #subscribeToVisibilityChanges(): void {
+    // Only subscribe in browser environments
+    if (
+      typeof document === `object` &&
+      typeof document.hidden === `boolean` &&
+      typeof document.addEventListener === `function`
+    ) {
+      const visibilityHandler = (): void => {
+        if (document.hidden) {
+          this.#pause()
+        } else {
+          this.#resume()
+        }
+      }
+
+      document.addEventListener(`visibilitychange`, visibilityHandler)
+
+      // Store cleanup function to remove the event listener
+      // Check document still exists (may be undefined in tests after cleanup)
+      this.#unsubscribeFromVisibilityChanges = () => {
+        if (typeof document === `object`) {
+          document.removeEventListener(`visibilitychange`, visibilityHandler)
+        }
+      }
+
+      // Check initial state - page might already be hidden when stream starts
+      if (document.hidden) {
+        this.#pause()
+      }
+    }
+  }
+
+  /**
+   * Pause the stream when page becomes hidden.
+   * Aborts any in-flight request to free resources.
+   * Creates a promise that pull() will await while paused.
+   */
+  #pause(): void {
+    if (this.#state === `active`) {
+      this.#state = `pause-requested`
+      // Create promise that pull() will await
+      this.#pausePromise = new Promise((resolve) => {
+        this.#pauseResolve = resolve
+      })
+      // Abort current request if any
+      this.#requestAbortController?.abort(PAUSE_STREAM)
+    }
+  }
+
+  /**
+   * Resume the stream when page becomes visible.
+   * Resolves the pause promise to unblock pull().
+   */
+  #resume(): void {
+    if (this.#state === `paused` || this.#state === `pause-requested`) {
+      // Don't resume if the user's signal is already aborted
+      if (this.#abortController.signal.aborted) {
+        return
+      }
+
+      // Transition to active and resolve the pause promise
+      this.#state = `active`
+      this.#justResumedFromPause = true // Flag for single-shot skip of live param
+      this.#pauseResolve?.()
+      this.#pausePromise = undefined
+      this.#pauseResolve = undefined
+    }
   }
 
   // --- Response metadata getters ---
@@ -174,6 +284,20 @@ 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
+  }
+
   // =================================
   // Internal helpers
   // =================================
@@ -189,10 +313,12 @@ export class StreamResponseImpl<
   }
 
   #markClosed(): void {
+    this.#unsubscribeFromVisibilityChanges?.()
     this.#closedResolve()
   }
 
   #markError(err: Error): void {
+    this.#unsubscribeFromVisibilityChanges?.()
     this.#closedReject(err)
   }
 
@@ -228,10 +354,10 @@ 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)
 
     // Update response metadata to reflect latest server response
     this.#headers = response.headers
@@ -288,12 +414,12 @@ export class StreamResponseImpl<
    * 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
     }
   }
 
@@ -388,13 +514,19 @@ export class StreamResponseImpl<
     // Track new connection start
     this.#markSSEConnectionStart()
 
+    // Create new per-request abort controller for this SSE connection
+    this.#requestAbortController = new AbortController()
+
     const newSSEResponse = await this.#startSSE(
       this.offset,
       this.cursor,
-      this.#abortController.signal
+      this.#requestAbortController.signal
     )
     if (newSSEResponse.body) {
-      return parseSSEStream(newSSEResponse.body, this.#abortController.signal)
+      return parseSSEStream(
+        newSSEResponse.body,
+        this.#requestAbortController.signal
+      )
     }
     return null
   }
@@ -548,10 +680,12 @@ export class StreamResponseImpl<
             if (isSSE && firstResponse.body) {
               // Track SSE connection start for resilience monitoring
               this.#markSSEConnectionStart()
+              // Create per-request abort controller for SSE connection
+              this.#requestAbortController = new AbortController()
               // Start parsing SSE events
               sseEventIterator = parseSSEStream(
                 firstResponse.body,
-                this.#abortController.signal
+                this.#requestAbortController.signal
               )
               // Fall through to SSE processing below
             } else {
@@ -570,6 +704,30 @@ export class StreamResponseImpl<
 
           // SSE mode: process events from the SSE stream
           if (sseEventIterator) {
+            // Check for pause state before processing SSE events
+            if (this.#state === `pause-requested` || this.#state === `paused`) {
+              this.#state = `paused`
+              if (this.#pausePromise) {
+                await this.#pausePromise
+              }
+              // After resume, check if we should still continue
+              if (this.#abortController.signal.aborted) {
+                this.#markClosed()
+                controller.close()
+                return
+              }
+              // Reconnect SSE after resume
+              const newIterator = await this.#trySSEReconnect()
+              if (newIterator) {
+                sseEventIterator = newIterator
+              } else {
+                // Could not reconnect - close the stream
+                this.#markClosed()
+                controller.close()
+                return
+              }
+            }
+
             // Keep reading events until we get data or stream ends
             // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
             while (true) {
@@ -604,16 +762,39 @@ export class StreamResponseImpl<
 
           // Long-poll mode: continue with live updates if needed
           if (this.#shouldContinueLive()) {
+            // If paused or pause-requested, await the pause promise
+            // This blocks pull() until resume() is called, avoiding deadlock
+            if (this.#state === `pause-requested` || this.#state === `paused`) {
+              this.#state = `paused`
+              if (this.#pausePromise) {
+                await this.#pausePromise
+              }
+              // After resume, check if we should still continue
+              if (this.#abortController.signal.aborted) {
+                this.#markClosed()
+                controller.close()
+                return
+              }
+            }
+
             if (this.#abortController.signal.aborted) {
               this.#markClosed()
               controller.close()
               return
             }
 
+            // Consume the single-shot resume flag (only first fetch after resume skips live param)
+            const resumingFromPause = this.#justResumedFromPause
+            this.#justResumedFromPause = false
+
+            // Create a new AbortController for this request (so we can abort on pause)
+            this.#requestAbortController = new AbortController()
+
             const response = await this.#fetchNext(
               this.offset,
               this.cursor,
-              this.#abortController.signal
+              this.#requestAbortController.signal,
+              resumingFromPause
             )
 
             this.#updateStateFromResponse(response)
@@ -626,6 +807,21 @@ export class StreamResponseImpl<
           this.#markClosed()
           controller.close()
         } catch (err) {
+          // Check if this was a pause-triggered abort
+          // Treat PAUSE_STREAM aborts as benign regardless of current state
+          // (handles race where resume() was called before abort completed)
+          if (
+            this.#requestAbortController?.signal.aborted &&
+            this.#requestAbortController.signal.reason === PAUSE_STREAM
+          ) {
+            // Only transition to paused if we're still in pause-requested state
+            if (this.#state === `pause-requested`) {
+              this.#state = `paused`
+            }
+            // Return - either we're paused, or already resumed and next pull will proceed
+            return
+          }
+
           if (this.#abortController.signal.aborted) {
             this.#markClosed()
             controller.close()
@@ -638,6 +834,7 @@ export class StreamResponseImpl<
 
       cancel: () => {
         this.#abortController.abort()
+        this.#unsubscribeFromVisibilityChanges?.()
         this.#markClosed()
       },
     })
@@ -704,7 +901,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 {
@@ -838,7 +1045,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
@@ -882,7 +1099,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()
@@ -903,9 +1120,20 @@ export class StreamResponseImpl<
           // 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,
@@ -938,7 +1166,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()
@@ -956,6 +1186,7 @@ export class StreamResponseImpl<
 
           const buffer = await response.arrayBuffer()
 
+          // Await callback (handles both sync and async)
           await subscriber({
             data: new Uint8Array(buffer),
             offset,
@@ -988,7 +1219,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()
@@ -1006,6 +1239,7 @@ export class StreamResponseImpl<
 
           const text = await response.text()
 
+          // Await callback (handles both sync and async)
           await subscriber({
             text,
             offset,
@@ -1044,6 +1278,7 @@ export class StreamResponseImpl<
 
   cancel(reason?: unknown): void {
     this.#abortController.abort(reason)
+    this.#unsubscribeFromVisibilityChanges?.()
     this.#markClosed()
   }
 

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"
 
 /**
@@ -79,10 +80,17 @@ export async function* parseSSEStream(
                   streamCursor: control.streamCursor,
                   upToDate: control.upToDate,
                 }
-              } 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:`)) {
@@ -122,8 +130,13 @@ export async function* parseSSEStream(
             streamCursor: control.streamCursor,
             upToDate: control.upToDate,
           }
-        } 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`
+          )
         }
       }
     }