@durable-streams/client 0.1.0

package/src/sse.ts

@@ -0,0 +1,130 @@
+/**
+ * SSE (Server-Sent Events) parsing utilities for the durable streams protocol.
+ *
+ * SSE format from protocol:
+ * - `event: data` events contain the stream data
+ * - `event: control` events contain `streamNextOffset` and optional `streamCursor` and `upToDate`
+ */
+
+import type { Offset } from "./types"
+
+/**
+ * Parsed SSE event from the stream.
+ */
+export interface SSEDataEvent {
+  type: `data`
+  data: string
+}
+
+export interface SSEControlEvent {
+  type: `control`
+  streamNextOffset: Offset
+  streamCursor?: string
+  upToDate?: boolean
+}
+
+export type SSEEvent = SSEDataEvent | SSEControlEvent
+
+/**
+ * Parse SSE events from a ReadableStream<Uint8Array>.
+ * Yields parsed events as they arrive.
+ */
+export async function* parseSSEStream(
+  stream: ReadableStream<Uint8Array>,
+  signal?: AbortSignal
+): AsyncGenerator<SSEEvent, void, undefined> {
+  const reader = stream.getReader()
+  const decoder = new TextDecoder()
+  let buffer = ``
+  let currentEvent: { type?: string; data: Array<string> } = { data: [] }
+
+  try {
+    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+    while (true) {
+      if (signal?.aborted) {
+        break
+      }
+
+      const { done, value } = await reader.read()
+      if (done) break
+
+      buffer += decoder.decode(value, { stream: true })
+
+      // Process complete lines
+      const lines = buffer.split(`\n`)
+      // Keep the last incomplete line in the buffer
+      buffer = lines.pop() ?? ``
+
+      for (const line of lines) {
+        if (line === ``) {
+          // Empty line signals end of event
+          if (currentEvent.type && currentEvent.data.length > 0) {
+            const dataStr = currentEvent.data.join(`\n`)
+
+            if (currentEvent.type === `data`) {
+              yield { type: `data`, data: dataStr }
+            } else if (currentEvent.type === `control`) {
+              try {
+                const control = JSON.parse(dataStr) as {
+                  streamNextOffset: Offset
+                  streamCursor?: string
+                  upToDate?: boolean
+                }
+                yield {
+                  type: `control`,
+                  streamNextOffset: control.streamNextOffset,
+                  streamCursor: control.streamCursor,
+                  upToDate: control.upToDate,
+                }
+              } catch {
+                // Invalid control event, skip
+              }
+            }
+          }
+          currentEvent = { data: [] }
+        } else if (line.startsWith(`event:`)) {
+          currentEvent.type = line.slice(6).trim()
+        } else if (line.startsWith(`data:`)) {
+          // Per SSE spec, strip the optional space after "data:"
+          const content = line.slice(5)
+          currentEvent.data.push(
+            content.startsWith(` `) ? content.slice(1) : content
+          )
+        }
+        // Ignore other fields (id, retry, comments)
+      }
+    }
+
+    // Handle any remaining data
+    const remaining = decoder.decode()
+    if (remaining) {
+      buffer += remaining
+    }
+
+    // Process any final event
+    if (buffer && currentEvent.type && currentEvent.data.length > 0) {
+      const dataStr = currentEvent.data.join(`\n`)
+      if (currentEvent.type === `data`) {
+        yield { type: `data`, data: dataStr }
+      } else if (currentEvent.type === `control`) {
+        try {
+          const control = JSON.parse(dataStr) as {
+            streamNextOffset: Offset
+            streamCursor?: string
+            upToDate?: boolean
+          }
+          yield {
+            type: `control`,
+            streamNextOffset: control.streamNextOffset,
+            streamCursor: control.streamCursor,
+            upToDate: control.upToDate,
+          }
+        } catch {
+          // Invalid control event, skip
+        }
+      }
+    }
+  } finally {
+    reader.releaseLock()
+  }
+}

package/src/stream-api.ts

@@ -0,0 +1,284 @@
+/**
+ * Standalone stream() function - the fetch-like read API.
+ *
+ * This is the primary API for consumers who only need to read from streams.
+ */
+
+import {
+  LIVE_QUERY_PARAM,
+  OFFSET_QUERY_PARAM,
+  STREAM_CURSOR_HEADER,
+  STREAM_OFFSET_HEADER,
+  STREAM_UP_TO_DATE_HEADER,
+} from "./constants"
+import { DurableStreamError, FetchBackoffAbortError } from "./error"
+import { BackoffDefaults, createFetchWithBackoff } from "./fetch"
+import { StreamResponseImpl } from "./response"
+import { handleErrorResponse, resolveHeaders, resolveParams } from "./utils"
+import type { LiveMode, Offset, StreamOptions, StreamResponse } from "./types"
+
+/**
+ * Create a streaming session to read from a durable stream.
+ *
+ * This is a fetch-like API:
+ * - The promise resolves after the first network request succeeds
+ * - It rejects for auth/404/other protocol errors
+ * - Returns a StreamResponse for consuming the data
+ *
+ * @example
+ * ```typescript
+ * // Catch-up JSON:
+ * const res = await stream<{ message: string }>({
+ *   url,
+ *   auth,
+ *   offset: "0",
+ *   live: false,
+ * })
+ * const items = await res.json()
+ *
+ * // Live JSON:
+ * const live = await stream<{ message: string }>({
+ *   url,
+ *   auth,
+ *   offset: savedOffset,
+ *   live: "auto",
+ * })
+ * live.subscribeJson(async (batch) => {
+ *   for (const item of batch.items) {
+ *     handle(item)
+ *   }
+ * })
+ * ```
+ */
+export async function stream<TJson = unknown>(
+  options: StreamOptions
+): Promise<StreamResponse<TJson>> {
+  // Validate options
+  if (!options.url) {
+    throw new DurableStreamError(
+      `Invalid stream options: missing required url parameter`,
+      `BAD_REQUEST`
+    )
+  }
+
+  // Mutable options that can be updated by onError handler
+  let currentHeaders = options.headers
+  let currentParams = options.params
+
+  // Retry loop for onError handling
+  // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+  while (true) {
+    try {
+      return await streamInternal<TJson>({
+        ...options,
+        headers: currentHeaders,
+        params: currentParams,
+      })
+    } catch (err) {
+      // If there's an onError handler, give it a chance to recover
+      if (options.onError) {
+        const retryOpts = await options.onError(
+          err instanceof Error ? err : new Error(String(err))
+        )
+
+        // If handler returns void/undefined, stop retrying
+        if (retryOpts === undefined) {
+          throw err
+        }
+
+        // Merge returned params/headers for retry
+        if (retryOpts.params) {
+          currentParams = {
+            ...currentParams,
+            ...retryOpts.params,
+          }
+        }
+        if (retryOpts.headers) {
+          currentHeaders = {
+            ...currentHeaders,
+            ...retryOpts.headers,
+          }
+        }
+
+        // Continue to retry with updated options
+        continue
+      }
+
+      // No onError handler, just throw
+      throw err
+    }
+  }
+}
+
+/**
+ * Internal implementation of stream that doesn't handle onError retries.
+ */
+async function streamInternal<TJson = unknown>(
+  options: StreamOptions
+): Promise<StreamResponse<TJson>> {
+  // Normalize URL
+  const url = options.url instanceof URL ? options.url.toString() : options.url
+
+  // Build the first request
+  const fetchUrl = new URL(url)
+
+  // Set offset query param
+  const startOffset = options.offset ?? `-1`
+  fetchUrl.searchParams.set(OFFSET_QUERY_PARAM, startOffset)
+
+  // Set live query param for explicit modes
+  const live: LiveMode = options.live ?? `auto`
+  if (live === `long-poll` || live === `sse`) {
+    fetchUrl.searchParams.set(LIVE_QUERY_PARAM, live)
+  }
+
+  // Add custom params
+  const params = await resolveParams(options.params)
+  for (const [key, value] of Object.entries(params)) {
+    fetchUrl.searchParams.set(key, value)
+  }
+
+  // Build headers
+  const headers = await resolveHeaders(options.headers)
+
+  // Create abort controller
+  const abortController = new AbortController()
+  if (options.signal) {
+    options.signal.addEventListener(
+      `abort`,
+      () => abortController.abort(options.signal?.reason),
+      { once: true }
+    )
+  }
+
+  // Get fetch client with backoff
+  const baseFetchClient =
+    options.fetch ?? ((...args: Parameters<typeof fetch>) => fetch(...args))
+  const backoffOptions = options.backoffOptions ?? BackoffDefaults
+  const fetchClient = createFetchWithBackoff(baseFetchClient, backoffOptions)
+
+  // Make the first request
+  // Backoff client will throw FetchError for non-OK responses
+  let firstResponse: Response
+  try {
+    firstResponse = await fetchClient(fetchUrl.toString(), {
+      method: `GET`,
+      headers,
+      signal: abortController.signal,
+    })
+  } catch (err) {
+    if (err instanceof FetchBackoffAbortError) {
+      throw new DurableStreamError(`Stream request was aborted`, `UNKNOWN`)
+    }
+    // Let other errors (including FetchError) propagate to onError handler
+    throw err
+  }
+
+  // Extract metadata from headers
+  const contentType = firstResponse.headers.get(`content-type`) ?? undefined
+  const initialOffset =
+    firstResponse.headers.get(STREAM_OFFSET_HEADER) ?? startOffset
+  const initialCursor =
+    firstResponse.headers.get(STREAM_CURSOR_HEADER) ?? undefined
+  const initialUpToDate = firstResponse.headers.has(STREAM_UP_TO_DATE_HEADER)
+
+  // Determine if JSON mode
+  const isJsonMode =
+    options.json === true ||
+    (contentType?.includes(`application/json`) ?? false)
+
+  // Create the fetch function for subsequent requests
+  const fetchNext = async (
+    offset: Offset,
+    cursor: string | undefined,
+    signal: AbortSignal
+  ): Promise<Response> => {
+    const nextUrl = new URL(url)
+    nextUrl.searchParams.set(OFFSET_QUERY_PARAM, offset)
+
+    // For subsequent requests in auto mode, use long-poll
+    if (live === `auto` || live === `long-poll`) {
+      nextUrl.searchParams.set(LIVE_QUERY_PARAM, `long-poll`)
+    } else if (live === `sse`) {
+      nextUrl.searchParams.set(LIVE_QUERY_PARAM, `sse`)
+    }
+
+    if (cursor) {
+      nextUrl.searchParams.set(`cursor`, cursor)
+    }
+
+    // Resolve params per-request (for dynamic values)
+    const nextParams = await resolveParams(options.params)
+    for (const [key, value] of Object.entries(nextParams)) {
+      nextUrl.searchParams.set(key, value)
+    }
+
+    const nextHeaders = await resolveHeaders(options.headers)
+
+    const response = await fetchClient(nextUrl.toString(), {
+      method: `GET`,
+      headers: nextHeaders,
+      signal,
+    })
+
+    if (!response.ok) {
+      await handleErrorResponse(response, url)
+    }
+
+    return response
+  }
+
+  // Create SSE start function (for SSE mode reconnection)
+  const startSSE =
+    live === `sse`
+      ? async (
+          offset: Offset,
+          cursor: string | undefined,
+          signal: AbortSignal
+        ): Promise<Response> => {
+          const sseUrl = new URL(url)
+          sseUrl.searchParams.set(OFFSET_QUERY_PARAM, offset)
+          sseUrl.searchParams.set(LIVE_QUERY_PARAM, `sse`)
+          if (cursor) {
+            sseUrl.searchParams.set(`cursor`, cursor)
+          }
+
+          // Resolve params per-request (for dynamic values)
+          const sseParams = await resolveParams(options.params)
+          for (const [key, value] of Object.entries(sseParams)) {
+            sseUrl.searchParams.set(key, value)
+          }
+
+          const sseHeaders = await resolveHeaders(options.headers)
+
+          const response = await fetchClient(sseUrl.toString(), {
+            method: `GET`,
+            headers: sseHeaders,
+            signal,
+          })
+
+          if (!response.ok) {
+            await handleErrorResponse(response, url)
+          }
+
+          return response
+        }
+      : undefined
+
+  // Create and return the StreamResponse
+  return new StreamResponseImpl<TJson>({
+    url,
+    contentType,
+    live,
+    startOffset,
+    isJsonMode,
+    initialOffset,
+    initialCursor,
+    initialUpToDate,
+    firstResponse,
+    abortController,
+    fetchNext,
+    startSSE,
+    sseResilience: options.sseResilience,
+  })
+}