@durable-streams/client 0.1.4 → 0.2.0

package/src/stream-api.ts

@@ -14,7 +14,12 @@ import {
 import { DurableStreamError, FetchBackoffAbortError } from "./error"
 import { BackoffDefaults, createFetchWithBackoff } from "./fetch"
 import { StreamResponseImpl } from "./response"
-import { handleErrorResponse, resolveHeaders, resolveParams } from "./utils"
+import {
+  handleErrorResponse,
+  resolveHeaders,
+  resolveParams,
+  warnIfUsingHttpInBrowser,
+} from "./utils"
 import type { LiveMode, Offset, StreamOptions, StreamResponse } from "./types"
 
 /**
@@ -41,7 +46,7 @@ import type { LiveMode, Offset, StreamOptions, StreamResponse } from "./types"
  *   url,
  *   auth,
  *   offset: savedOffset,
- *   live: "auto",
+ *   live: true,
  * })
  * live.subscribeJson(async (batch) => {
  *   for (const item of batch.items) {
@@ -119,6 +124,9 @@ async function streamInternal<TJson = unknown>(
   // Normalize URL
   const url = options.url instanceof URL ? options.url.toString() : options.url
 
+  // Warn if using HTTP in browser (can cause connection limit issues)
+  warnIfUsingHttpInBrowser(url, options.warnOnHttp)
+
   // Build the first request
   const fetchUrl = new URL(url)
 
@@ -127,7 +135,8 @@ async function streamInternal<TJson = unknown>(
   fetchUrl.searchParams.set(OFFSET_QUERY_PARAM, startOffset)
 
   // Set live query param for explicit modes
-  const live: LiveMode = options.live ?? `auto`
+  // true means auto-select (no query param, handled by consumption method)
+  const live: LiveMode = options.live ?? true
   if (live === `long-poll` || live === `sse`) {
     fetchUrl.searchParams.set(LIVE_QUERY_PARAM, live)
   }
@@ -191,16 +200,20 @@ async function streamInternal<TJson = unknown>(
   const fetchNext = async (
     offset: Offset,
     cursor: string | undefined,
-    signal: AbortSignal
+    signal: AbortSignal,
+    resumingFromPause?: boolean
   ): 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`)
+    // For subsequent requests, set live mode unless resuming from pause
+    // (resuming from pause needs immediate response for UI status)
+    if (!resumingFromPause) {
+      if (live === `sse`) {
+        nextUrl.searchParams.set(LIVE_QUERY_PARAM, `sse`)
+      } else if (live === true || live === `long-poll`) {
+        nextUrl.searchParams.set(LIVE_QUERY_PARAM, `long-poll`)
+      }
     }
 
     if (cursor) {

package/src/stream.ts

@@ -11,6 +11,7 @@ import {
   InvalidSignalError,
   MissingStreamUrlError,
 } from "./error"
+import { IdempotentProducer } from "./idempotent-producer"
 import {
   SSE_COMPATIBLE_CONTENT_TYPES,
   STREAM_EXPIRES_AT_HEADER,
@@ -37,6 +38,7 @@ import type {
   CreateOptions,
   HeadResult,
   HeadersRecord,
+  IdempotentProducerOptions,
   MaybePromise,
   ParamsRecord,
   StreamErrorHandler,
@@ -49,7 +51,7 @@ import type {
  * Queued message for batching.
  */
 interface QueuedMessage {
-  data: unknown
+  data: Uint8Array | string
   seq?: string
   contentType?: string
   signal?: AbortSignal
@@ -71,10 +73,7 @@ function normalizeContentType(contentType: string | undefined): string {
  */
 function isPromiseLike(value: unknown): value is PromiseLike<unknown> {
   return (
-    value !== null &&
-    typeof value === `object` &&
-    `then` in value &&
-    typeof (value as PromiseLike<unknown>).then === `function`
+    value != null && typeof (value as PromiseLike<unknown>).then === `function`
   )
 }
 
@@ -121,7 +120,7 @@ export interface DurableStreamOptions extends StreamHandleOptions {
  * });
  *
  * // Write data
- * await stream.append({ message: "hello" });
+ * await stream.append(JSON.stringify({ message: "hello" }));
  *
  * // Read with the new API
  * const res = await stream.stream<{ message: string }>();
@@ -350,23 +349,27 @@ export class DurableStream {
    * a POST is in-flight will be batched together into a single request.
    * This significantly improves throughput for high-frequency writes.
    *
-   * - `body` may be Uint8Array, string, or any JSON-serializable value (for JSON streams).
-   * - `body` may also be a Promise that resolves to any of the above types.
+   * - `body` must be string or Uint8Array.
+   * - For JSON streams, pass pre-serialized JSON strings.
+   * - `body` may also be a Promise that resolves to string or Uint8Array.
    * - Strings are encoded as UTF-8.
    * - `seq` (if provided) is sent as stream-seq (writer coordination).
    *
    * @example
    * ```typescript
-   * // Direct value
-   * await stream.append({ message: "hello" });
+   * // JSON stream - pass pre-serialized JSON
+   * await stream.append(JSON.stringify({ message: "hello" }));
+   *
+   * // Byte stream
+   * await stream.append("raw text data");
+   * await stream.append(new Uint8Array([1, 2, 3]));
    *
    * // Promise value - awaited before buffering
    * await stream.append(fetchData());
-   * await stream.append(Promise.all([a, b, c]));
    * ```
    */
   async append(
-    body: BodyInit | Uint8Array | string | unknown,
+    body: Uint8Array | string | Promise<Uint8Array | string>,
     opts?: AppendOptions
   ): Promise<void> {
     // Await promises before buffering
@@ -382,7 +385,7 @@ export class DurableStream {
    * Direct append without batching (used when batching is disabled).
    */
   async #appendDirect(
-    body: BodyInit | Uint8Array | string | unknown,
+    body: Uint8Array | string,
     opts?: AppendOptions
   ): Promise<void> {
     const { requestHeaders, fetchUrl } = await this.#buildRequest()
@@ -398,9 +401,11 @@ 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 bodyToEncode = isJson ? [body] : body
-    const encodedBody = encodeBody(bodyToEncode)
+    const bodyStr =
+      typeof body === `string` ? body : new TextDecoder().decode(body)
+    const encodedBody: BodyInit = isJson ? `[${bodyStr}]` : bodyStr
 
     const response = await this.#fetchClient(fetchUrl.toString(), {
       method: `POST`,
@@ -418,7 +423,7 @@ export class DurableStream {
    * Append with batching - buffers messages and sends them in batches.
    */
   async #appendWithBatching(
-    body: unknown,
+    body: Uint8Array | string,
     opts?: AppendOptions
   ): Promise<void> {
     return new Promise<void>((resolve, reject) => {
@@ -511,29 +516,17 @@ export class DurableStream {
       // 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((m) => m.data)
-      batchedBody = JSON.stringify(values)
+      // Input is pre-serialized JSON strings, join them into an array
+      const jsonStrings = batch.map((m) =>
+        typeof m.data === `string` ? m.data : new TextDecoder().decode(m.data)
+      )
+      batchedBody = `[${jsonStrings.join(`,`)}]`
     } else {
-      // For byte mode: concatenate all chunks
-      const totalSize = batch.reduce((sum, m) => {
-        const size =
-          typeof m.data === `string`
-            ? new TextEncoder().encode(m.data).length
-            : (m.data as Uint8Array).length
-        return sum + size
-      }, 0)
-
-      const concatenated = new Uint8Array(totalSize)
-      let offset = 0
-      for (const msg of batch) {
-        const bytes =
-          typeof msg.data === `string`
-            ? new TextEncoder().encode(msg.data)
-            : (msg.data as Uint8Array)
-        concatenated.set(bytes, offset)
-        offset += bytes.length
-      }
-      batchedBody = concatenated
+      // 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(``)
     }
 
     // Combine signals: stream-level signal + any per-message signals
@@ -634,6 +627,11 @@ export class DurableStream {
    * Returns a WritableStream that can be used with `pipeTo()` or
    * `pipeThrough()` from any ReadableStream source.
    *
+   * Uses IdempotentProducer internally for:
+   * - Automatic batching (controlled by lingerMs, maxBatchBytes)
+   * - Exactly-once delivery semantics
+   * - Streaming writes (doesn't buffer entire content in memory)
+   *
    * @example
    * ```typescript
    * // Pipe from fetch response
@@ -643,32 +641,55 @@ export class DurableStream {
    * // Pipe through a transform
    * const readable = someStream.pipeThrough(new TextEncoderStream());
    * await readable.pipeTo(stream.writable());
+   *
+   * // With custom producer options
+   * await source.pipeTo(stream.writable({
+   *   producerId: "my-producer",
+   *   lingerMs: 10,
+   *   maxBatchBytes: 64 * 1024,
+   * }));
    * ```
    */
-  writable(opts?: AppendOptions): WritableStream<Uint8Array | string> {
-    const chunks: Array<Uint8Array | string> = []
-    const stream = this
+  writable(
+    opts?: Pick<
+      IdempotentProducerOptions,
+      `lingerMs` | `maxBatchBytes` | `onError`
+    > & {
+      producerId?: string
+      signal?: AbortSignal
+    }
+  ): WritableStream<Uint8Array | string> {
+    // Generate a random producer ID if not provided
+    const producerId =
+      opts?.producerId ?? `writable-${crypto.randomUUID().slice(0, 8)}`
+
+    // Track async errors to surface in close() so pipeTo() rejects on failure
+    let writeError: Error | null = null
+
+    const producer = new IdempotentProducer(this, producerId, {
+      autoClaim: true, // Ephemeral producer, auto-claim epoch
+      lingerMs: opts?.lingerMs,
+      maxBatchBytes: opts?.maxBatchBytes,
+      onError: (error) => {
+        if (!writeError) writeError = error // Capture first error
+        opts?.onError?.(error) // Still call user's handler
+      },
+      signal: opts?.signal ?? this.#options.signal,
+    })
 
     return new WritableStream<Uint8Array | string>({
       write(chunk) {
-        chunks.push(chunk)
+        producer.append(chunk)
       },
       async close() {
-        if (chunks.length > 0) {
-          // Create a ReadableStream from collected chunks
-          const readable = new ReadableStream<Uint8Array | string>({
-            start(controller) {
-              for (const chunk of chunks) {
-                controller.enqueue(chunk)
-              }
-              controller.close()
-            },
-          })
-          await stream.appendStream(readable, opts)
-        }
+        await producer.flush()
+        await producer.close()
+        if (writeError) throw writeError // Causes pipeTo() to reject
       },
-      abort(reason) {
-        console.error(`WritableStream aborted:`, reason)
+      abort(_reason) {
+        producer.close().catch((err) => {
+          opts?.onError?.(err) // Report instead of swallowing
+        })
       },
     })
   }

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