@durable-streams/client 0.1.5 → 0.2.0

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
    */
@@ -518,6 +518,7 @@ export type DurableStreamErrorCode =
   | `RATE_LIMITED`
   | `ALREADY_CONSUMED`
   | `ALREADY_CLOSED`
+  | `PARSE_ERROR`
   | `UNKNOWN`
 
 /**
@@ -659,21 +660,21 @@ 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
 
   // =================================
   // 1) Accumulating helpers (Promise)
@@ -682,20 +683,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 +738,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