@durable-streams/client 0.1.5 → 0.2.1

package/src/types.ts

@@ -62,11 +62,11 @@ export type ParamsRecord = {
 /**
  * Live mode for reading from a stream.
  * - false: Catch-up only, stop at first `upToDate`
- * - "auto": Behavior driven by consumption method (default)
+ * - true: Auto-select best mode (SSE for JSON streams, long-poll for binary)
  * - "long-poll": Explicit long-poll mode for live updates
  * - "sse": Explicit server-sent events for live updates
  */
-export type LiveMode = false | `auto` | `long-poll` | `sse`
+export type LiveMode = boolean | `long-poll` | `sse`
 
 // ============================================================================
 // Stream Options (Read API)
@@ -136,7 +136,7 @@ export interface StreamOptions {
   /**
    * Live mode behavior:
    * - false: Catch-up only, stop at first `upToDate`
-   * - "auto" (default): Behavior driven by consumption method
+   * - true (default): Auto-select best mode (SSE for JSON, long-poll for binary)
    * - "long-poll": Explicit long-poll mode for live updates
    * - "sse": Explicit server-sent events for live updates
    */
@@ -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
 }
 
 /**
@@ -518,6 +577,8 @@ export type DurableStreamErrorCode =
   | `RATE_LIMITED`
   | `ALREADY_CONSUMED`
   | `ALREADY_CLOSED`
+  | `PARSE_ERROR`
+  | `STREAM_CLOSED`
   | `UNKNOWN`
 
 /**
@@ -659,21 +720,34 @@ export interface StreamResponse<TJson = unknown> {
    *
    * Use this for resuming reads after a disconnect or saving checkpoints.
    */
-  offset: Offset
+  readonly offset: Offset
 
   /**
    * Stream cursor for CDN collapsing (stream-cursor header).
    *
    * Updated after each chunk is delivered to the consumer.
    */
-  cursor?: string
+  readonly cursor?: string
 
   /**
    * Whether we've reached the current end of the stream (stream-up-to-date header).
    *
    * Updated after each chunk is delivered to the consumer.
    */
-  upToDate: boolean
+  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)
@@ -682,20 +756,20 @@ export interface StreamResponse<TJson = unknown> {
 
   /**
    * Accumulate raw bytes until first `upToDate` batch, then resolve.
-   * When used with `live: "auto"`, signals the session to stop after upToDate.
+   * When used with `live: true`, signals the session to stop after upToDate.
    */
   body: () => Promise<Uint8Array>
 
   /**
    * Accumulate JSON *items* across batches into a single array, resolve at `upToDate`.
    * Only valid in JSON-mode; throws otherwise.
-   * When used with `live: "auto"`, signals the session to stop after upToDate.
+   * When used with `live: true`, signals the session to stop after upToDate.
    */
   json: <T = TJson>() => Promise<Array<T>>
 
   /**
    * Accumulate text chunks into a single string, resolve at `upToDate`.
-   * When used with `live: "auto"`, signals the session to stop after upToDate.
+   * When used with `live: true`, signals the session to stop after upToDate.
    */
   text: () => Promise<string>
 
@@ -737,24 +811,35 @@ export interface StreamResponse<TJson = unknown> {
   /**
    * Subscribe to JSON batches as they arrive.
    * Returns unsubscribe function.
+   *
+   * The subscriber can be sync or async. If async, backpressure is applied
+   * (the next batch waits for the previous callback to complete).
    */
   subscribeJson: <T = TJson>(
-    subscriber: (batch: JsonBatch<T>) => Promise<void>
+    subscriber: (batch: JsonBatch<T>) => void | Promise<void>
   ) => () => void
 
   /**
    * Subscribe to raw byte chunks as they arrive.
    * Returns unsubscribe function.
+   *
+   * The subscriber can be sync or async. If async, backpressure is applied
+   * (the next chunk waits for the previous callback to complete).
    */
   subscribeBytes: (
-    subscriber: (chunk: ByteChunk) => Promise<void>
+    subscriber: (chunk: ByteChunk) => void | Promise<void>
   ) => () => void
 
   /**
    * Subscribe to text chunks as they arrive.
    * Returns unsubscribe function.
+   *
+   * The subscriber can be sync or async. If async, backpressure is applied
+   * (the next chunk waits for the previous callback to complete).
    */
-  subscribeText: (subscriber: (chunk: TextChunk) => Promise<void>) => () => void
+  subscribeText: (
+    subscriber: (chunk: TextChunk) => void | Promise<void>
+  ) => () => void
 
   // =====================
   // 4) Lifecycle

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`