@durable-streams/client 0.2.0 → 0.2.1

package/src/sse.ts

@@ -22,6 +22,7 @@ export interface SSEControlEvent {
   streamNextOffset: Offset
   streamCursor?: string
   upToDate?: boolean
+  streamClosed?: boolean
 }
 
 export type SSEEvent = SSEDataEvent | SSEControlEvent
@@ -73,12 +74,14 @@ 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 (err) {
                 // Control events contain critical offset data - don't silently ignore
@@ -94,7 +97,11 @@ export async function* parseSSEStream(
           }
           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)
@@ -123,12 +130,14 @@ 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 (err) {
           const preview =

package/src/stream-api.ts

@@ -7,8 +7,10 @@
 import {
   LIVE_QUERY_PARAM,
   OFFSET_QUERY_PARAM,
+  STREAM_CLOSED_HEADER,
   STREAM_CURSOR_HEADER,
   STREAM_OFFSET_HEADER,
+  STREAM_SSE_DATA_ENCODING_HEADER,
   STREAM_UP_TO_DATE_HEADER,
 } from "./constants"
 import { DurableStreamError, FetchBackoffAbortError } from "./error"
@@ -190,12 +192,21 @@ async function streamInternal<TJson = unknown>(
   const initialCursor =
     firstResponse.headers.get(STREAM_CURSOR_HEADER) ?? undefined
   const initialUpToDate = firstResponse.headers.has(STREAM_UP_TO_DATE_HEADER)
+  const initialStreamClosed =
+    firstResponse.headers.get(STREAM_CLOSED_HEADER)?.toLowerCase() === `true`
 
   // Determine if JSON mode
   const isJsonMode =
     options.json === true ||
     (contentType?.includes(`application/json`) ?? false)
 
+  // Detect SSE data encoding from response header (server auto-sets for binary streams)
+  const sseDataEncoding = firstResponse.headers.get(
+    STREAM_SSE_DATA_ENCODING_HEADER
+  )
+  const encoding =
+    sseDataEncoding === `base64` ? (`base64` as const) : undefined
+
   // Create the fetch function for subsequent requests
   const fetchNext = async (
     offset: Offset,
@@ -288,10 +299,12 @@ async function streamInternal<TJson = unknown>(
     initialOffset,
     initialCursor,
     initialUpToDate,
+    initialStreamClosed,
     firstResponse,
     abortController,
     fetchNext,
     startSSE,
     sseResilience: options.sseResilience,
+    encoding,
   })
 }

package/src/stream.ts

@@ -7,13 +7,13 @@
 import fastq from "fastq"
 
 import {
-  DurableStreamError,
   InvalidSignalError,
   MissingStreamUrlError,
+  StreamClosedError,
 } from "./error"
 import { IdempotentProducer } from "./idempotent-producer"
 import {
-  SSE_COMPATIBLE_CONTENT_TYPES,
+  STREAM_CLOSED_HEADER,
   STREAM_EXPIRES_AT_HEADER,
   STREAM_OFFSET_HEADER,
   STREAM_SEQ_HEADER,
@@ -35,6 +35,8 @@ import type { BackoffOptions } from "./fetch"
 import type { queueAsPromised } from "fastq"
 import type {
   AppendOptions,
+  CloseOptions,
+  CloseResult,
   CreateOptions,
   HeadResult,
   HeadersRecord,
@@ -204,6 +206,7 @@ export class DurableStream {
       ttlSeconds: opts.ttlSeconds,
       expiresAt: opts.expiresAt,
       body: opts.body,
+      closed: opts.closed,
     })
     return stream
   }
@@ -269,6 +272,8 @@ export class DurableStream {
     const offset = response.headers.get(STREAM_OFFSET_HEADER) ?? undefined
     const etag = response.headers.get(`etag`) ?? undefined
     const cacheControl = response.headers.get(`cache-control`) ?? undefined
+    const streamClosed =
+      response.headers.get(STREAM_CLOSED_HEADER)?.toLowerCase() === `true`
 
     // Update instance contentType
     if (contentType) {
@@ -281,6 +286,7 @@ export class DurableStream {
       offset,
       etag,
       cacheControl,
+      streamClosed,
     }
   }
 
@@ -300,6 +306,9 @@ export class DurableStream {
     if (opts?.expiresAt) {
       requestHeaders[STREAM_EXPIRES_AT_HEADER] = opts.expiresAt
     }
+    if (opts?.closed) {
+      requestHeaders[STREAM_CLOSED_HEADER] = `true`
+    }
 
     const body = encodeBody(opts?.body)
 
@@ -342,6 +351,84 @@ export class DurableStream {
     }
   }
 
+  /**
+   * Close the stream, optionally with a final message.
+   *
+   * After closing:
+   * - No further appends are permitted (server returns 409)
+   * - Readers can observe the closed state and treat it as EOF
+   * - The stream's data remains fully readable
+   *
+   * Closing is:
+   * - **Durable**: The closed state is persisted
+   * - **Monotonic**: Once closed, a stream cannot be reopened
+   *
+   * **Idempotency:**
+   * - `close()` without body: Idempotent — safe to call multiple times
+   * - `close({ body })` with body: NOT idempotent — throws `StreamClosedError`
+   *   if stream is already closed (use `IdempotentProducer.close()` for
+   *   idempotent close-with-body semantics)
+   *
+   * @returns CloseResult with the final offset
+   * @throws StreamClosedError if called with body on an already-closed stream
+   */
+  async close(opts?: CloseOptions): Promise<CloseResult> {
+    const { requestHeaders, fetchUrl } = await this.#buildRequest()
+
+    const contentType =
+      opts?.contentType ?? this.#options.contentType ?? this.contentType
+    if (contentType) {
+      requestHeaders[`content-type`] = contentType
+    }
+
+    // Always send Stream-Closed: true header for close operation
+    requestHeaders[STREAM_CLOSED_HEADER] = `true`
+
+    // For JSON mode with body, wrap in array
+    let body: BodyInit | undefined
+    if (opts?.body !== undefined) {
+      const isJson = normalizeContentType(contentType) === `application/json`
+      if (isJson) {
+        const bodyStr =
+          typeof opts.body === `string`
+            ? opts.body
+            : new TextDecoder().decode(opts.body)
+        body = `[${bodyStr}]`
+      } else {
+        body =
+          typeof opts.body === `string`
+            ? opts.body
+            : (opts.body as unknown as BodyInit)
+      }
+    }
+
+    const response = await this.#fetchClient(fetchUrl.toString(), {
+      method: `POST`,
+      headers: requestHeaders,
+      body,
+      signal: opts?.signal ?? this.#options.signal,
+    })
+
+    // Check for 409 Conflict with Stream-Closed header
+    if (response.status === 409) {
+      const isClosed =
+        response.headers.get(STREAM_CLOSED_HEADER)?.toLowerCase() === `true`
+      if (isClosed) {
+        const finalOffset =
+          response.headers.get(STREAM_OFFSET_HEADER) ?? undefined
+        throw new StreamClosedError(this.url, finalOffset)
+      }
+    }
+
+    if (!response.ok) {
+      await handleErrorResponse(response, this.url)
+    }
+
+    const finalOffset = response.headers.get(STREAM_OFFSET_HEADER) ?? ``
+
+    return { finalOffset }
+  }
+
   /**
    * Append a single payload to the stream.
    *
@@ -403,9 +490,24 @@ export class DurableStream {
     // For JSON mode, wrap body in array to match protocol (server flattens one level)
     // Input is pre-serialized JSON string
     const isJson = normalizeContentType(contentType) === `application/json`
-    const bodyStr =
-      typeof body === `string` ? body : new TextDecoder().decode(body)
-    const encodedBody: BodyInit = isJson ? `[${bodyStr}]` : bodyStr
+    let encodedBody: BodyInit
+    if (isJson) {
+      // JSON mode: decode as UTF-8 string and wrap in array
+      const bodyStr =
+        typeof body === `string` ? body : new TextDecoder().decode(body)
+      encodedBody = `[${bodyStr}]`
+    } else {
+      // Binary mode: preserve raw bytes
+      // Use ArrayBuffer for cross-platform BodyInit compatibility
+      if (typeof body === `string`) {
+        encodedBody = body
+      } else {
+        encodedBody = body.buffer.slice(
+          body.byteOffset,
+          body.byteOffset + body.byteLength
+        ) as ArrayBuffer
+      }
+    }
 
     const response = await this.#fetchClient(fetchUrl.toString(), {
       method: `POST`,
@@ -522,11 +624,43 @@ export class DurableStream {
       )
       batchedBody = `[${jsonStrings.join(`,`)}]`
     } else {
-      // For byte mode: concatenate all chunks as a string
-      const strings = batch.map((m) =>
-        typeof m.data === `string` ? m.data : new TextDecoder().decode(m.data)
-      )
-      batchedBody = strings.join(``)
+      // For byte mode: preserve original data types
+      // - Strings are concatenated as strings (for text/* content types)
+      // - Uint8Arrays are concatenated as binary (for application/octet-stream)
+      // - Mixed types: convert all to binary to avoid data corruption
+      const hasUint8Array = batch.some((m) => m.data instanceof Uint8Array)
+      const hasString = batch.some((m) => typeof m.data === `string`)
+
+      if (hasUint8Array && !hasString) {
+        // All binary: concatenate Uint8Arrays
+        const chunks = batch.map((m) => m.data as Uint8Array)
+        const totalLength = chunks.reduce((sum, c) => sum + c.length, 0)
+        const combined = new Uint8Array(totalLength)
+        let offset = 0
+        for (const chunk of chunks) {
+          combined.set(chunk, offset)
+          offset += chunk.length
+        }
+        batchedBody = combined
+      } else if (hasString && !hasUint8Array) {
+        // All strings: concatenate as string
+        batchedBody = batch.map((m) => m.data as string).join(``)
+      } else {
+        // Mixed types: convert strings to binary and concatenate
+        // This preserves binary data integrity
+        const encoder = new TextEncoder()
+        const chunks = batch.map((m) =>
+          typeof m.data === `string` ? encoder.encode(m.data) : m.data
+        )
+        const totalLength = chunks.reduce((sum, c) => sum + c.length, 0)
+        const combined = new Uint8Array(totalLength)
+        let offset = 0
+        for (const chunk of chunks) {
+          combined.set(chunk, offset)
+          offset += chunk.length
+        }
+        batchedBody = combined
+      }
     }
 
     // Combine signals: stream-level signal + any per-message signals
@@ -682,12 +816,13 @@ export class DurableStream {
         producer.append(chunk)
       },
       async close() {
-        await producer.flush()
+        // close() flushes pending and closes the stream (EOF)
         await producer.close()
         if (writeError) throw writeError // Causes pipeTo() to reject
       },
       abort(_reason) {
-        producer.close().catch((err) => {
+        // detach() stops the producer without closing the stream
+        producer.detach().catch((err) => {
           opts?.onError?.(err) // Report instead of swallowing
         })
       },
@@ -736,20 +871,6 @@ export class DurableStream {
   async stream<TJson = unknown>(
     options?: Omit<StreamOptions, `url`>
   ): Promise<StreamResponse<TJson>> {
-    // Check SSE compatibility if SSE mode is requested
-    if (options?.live === `sse` && this.contentType) {
-      const isSSECompatible = SSE_COMPATIBLE_CONTENT_TYPES.some((prefix) =>
-        this.contentType!.startsWith(prefix)
-      )
-      if (!isSSECompatible) {
-        throw new DurableStreamError(
-          `SSE is not supported for content-type: ${this.contentType}`,
-          `SSE_NOT_SUPPORTED`,
-          400
-        )
-      }
-    }
-
     // Merge handle-level and call-specific headers
     const mergedHeaders: HeadersRecord = {
       ...this.#options.headers,

package/src/types.ts

@@ -228,6 +228,12 @@ export interface JsonBatchMeta {
    * Last Stream-Cursor / streamCursor, if present.
    */
   cursor?: string
+
+  /**
+   * Whether the stream is closed and this batch contains the final data.
+   * When true, no more data will ever be appended to the stream.
+   */
+  streamClosed: boolean
 }
 
 /**
@@ -357,6 +363,18 @@ export interface CreateOptions extends StreamHandleOptions {
    * @default true
    */
   batching?: boolean
+
+  /**
+   * If true, create the stream in the closed state.
+   * Any body provided becomes the complete and final content.
+   *
+   * Useful for:
+   * - Cached responses
+   * - Placeholder errors
+   * - Pre-computed results
+   * - Single-message streams that are immediately complete
+   */
+  closed?: boolean
 }
 
 /**
@@ -403,6 +421,41 @@ export interface AppendOptions {
   producerSeq?: number
 }
 
+/**
+ * Result of a close operation.
+ */
+export interface CloseResult {
+  /**
+   * The final offset of the stream.
+   * This is the offset after the last byte (including any final message).
+   * Returned via the `Stream-Next-Offset` header.
+   */
+  finalOffset: Offset
+}
+
+/**
+ * Options for closing a stream.
+ */
+export interface CloseOptions {
+  /**
+   * Optional final message to append atomically with close.
+   * For JSON streams, pass a pre-serialized JSON string.
+   * Strings are UTF-8 encoded.
+   */
+  body?: Uint8Array | string
+
+  /**
+   * Content type for the final message.
+   * Defaults to the stream's content type. Must match if provided.
+   */
+  contentType?: string
+
+  /**
+   * AbortSignal for this operation.
+   */
+  signal?: AbortSignal
+}
+
 /**
  * Legacy live mode type (internal use only).
  * @internal
@@ -470,6 +523,12 @@ export interface HeadResult {
    * Cache-Control header value.
    */
   cacheControl?: string
+
+  /**
+   * Whether the stream is closed.
+   * When true, no further appends are permitted.
+   */
+  streamClosed: boolean
 }
 
 /**
@@ -519,6 +578,7 @@ export type DurableStreamErrorCode =
   | `ALREADY_CONSUMED`
   | `ALREADY_CLOSED`
   | `PARSE_ERROR`
+  | `STREAM_CLOSED`
   | `UNKNOWN`
 
 /**
@@ -676,6 +736,19 @@ export interface StreamResponse<TJson = unknown> {
    */
   readonly upToDate: boolean
 
+  /**
+   * Whether the stream is closed (EOF).
+   *
+   * When true, no more data will ever be appended to the stream.
+   * This is updated after each chunk is delivered to the consumer.
+   *
+   * In live mode, when streamClosed becomes true:
+   * - Long-poll requests return immediately (no waiting)
+   * - SSE connections are closed by the server
+   * - Clients stop reconnecting automatically
+   */
+  readonly streamClosed: boolean
+
   // =================================
   // 1) Accumulating helpers (Promise)
   // =================================

package/src/utils.ts

@@ -2,7 +2,8 @@
  * Shared utility functions for the Durable Streams client.
  */
 
-import { DurableStreamError } from "./error"
+import { STREAM_CLOSED_HEADER, STREAM_OFFSET_HEADER } from "./constants"
+import { DurableStreamError, StreamClosedError } from "./error"
 import type { HeadersRecord, MaybePromise } from "./types"
 
 /**
@@ -45,6 +46,14 @@ export async function handleErrorResponse(
   }
 
   if (status === 409) {
+    // Check if this is a stream closed error
+    const streamClosedHeader = response.headers.get(STREAM_CLOSED_HEADER)
+    if (streamClosedHeader?.toLowerCase() === `true`) {
+      const finalOffset =
+        response.headers.get(STREAM_OFFSET_HEADER) ?? undefined
+      throw new StreamClosedError(url, finalOffset)
+    }
+
     // Context-specific 409 messages
     const message =
       context?.operation === `create`