@durable-streams/client 0.1.4 → 0.2.0

package/dist/index.d.cts

@@ -168,11 +168,11 @@ 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
 */
-type LiveMode = false | `auto` | `long-poll` | `sse`;
+type LiveMode = boolean | `long-poll` | `sse`;
 /**
 * Options for the stream() function (read-only API).
 */
@@ -230,7 +230,7 @@ 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
   */
@@ -521,7 +521,7 @@ interface HeadResult {
 /**
 * Error codes for DurableStreamError.
 */
-type DurableStreamErrorCode = `NOT_FOUND` | `CONFLICT_SEQ` | `CONFLICT_EXISTS` | `BAD_REQUEST` | `BUSY` | `SSE_NOT_SUPPORTED` | `UNAUTHORIZED` | `FORBIDDEN` | `RATE_LIMITED` | `ALREADY_CONSUMED` | `ALREADY_CLOSED` | `UNKNOWN`;
+type DurableStreamErrorCode = `NOT_FOUND` | `CONFLICT_SEQ` | `CONFLICT_EXISTS` | `BAD_REQUEST` | `BUSY` | `SSE_NOT_SUPPORTED` | `UNAUTHORIZED` | `FORBIDDEN` | `RATE_LIMITED` | `ALREADY_CONSUMED` | `ALREADY_CLOSED` | `PARSE_ERROR` | `UNKNOWN`;
 /**
 * Options returned from onError handler to retry with modified params/headers.
 * Following the Electric client pattern.
@@ -638,33 +638,33 @@ 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;
   /**
   * 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>;
   /**
@@ -692,18 +692,27 @@ 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>) => () => void;
+  subscribeJson: <T = TJson>(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>) => () => void;
+  subscribeBytes: (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;
   /**
   * Cancel the underlying session (abort HTTP, close SSE, stop long-polls).
   */
@@ -800,7 +809,7 @@ interface IdempotentAppendResult {
 *   url,
 *   auth,
 *   offset: savedOffset,
-*   live: "auto",
+*   live: true,
 * })
 * live.subscribeJson(async (batch) => {
 *   for (const item of batch.items) {
@@ -853,7 +862,7 @@ 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 }>();
@@ -931,22 +940,26 @@ declare 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]));
   * ```
   */
-  append(body: BodyInit | Uint8Array | string | unknown, opts?: AppendOptions): Promise<void>;
+  append(body: Uint8Array | string | Promise<Uint8Array | string>, opts?: AppendOptions): Promise<void>;
   /**
   * Append a streaming body to the stream.
   *
@@ -986,6 +999,11 @@ declare 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
@@ -995,9 +1013,19 @@ declare 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>;
+  writable(opts?: Pick<IdempotentProducerOptions, `lingerMs` | `maxBatchBytes` | `onError`> & {
+    producerId?: string;
+    signal?: AbortSignal;
+  }): WritableStream<Uint8Array | string>;
   /**
   * Start a fetch-like streaming session against this handle's URL/headers/params.
   * The first request is made inside this method; it resolves when we have
@@ -1132,12 +1160,22 @@ declare class IdempotentProducer {
   * Errors are reported via onError callback if configured. Use flush() to
   * wait for all pending messages to be sent.
   *
-  * For JSON streams, pass native objects (which will be serialized internally).
+  * For JSON streams, pass pre-serialized JSON strings.
   * For byte streams, pass string or Uint8Array.
   *
-  * @param body - Data to append (object for JSON streams, string or Uint8Array for byte streams)
+  * @param body - Data to append (string or Uint8Array)
+  *
+  * @example
+  * ```typescript
+  * // JSON stream
+  * producer.append(JSON.stringify({ message: "hello" }));
+  *
+  * // Byte stream
+  * producer.append("raw text data");
+  * producer.append(new Uint8Array([1, 2, 3]));
+  * ```
   */
-  append(body: Uint8Array | string | unknown): void;
+  append(body: Uint8Array | string): void;
   /**
   * Send any pending batch immediately and wait for all in-flight batches.
   *

package/dist/index.d.ts

@@ -168,11 +168,11 @@ 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
 */
-type LiveMode = false | `auto` | `long-poll` | `sse`;
+type LiveMode = boolean | `long-poll` | `sse`;
 /**
 * Options for the stream() function (read-only API).
 */
@@ -230,7 +230,7 @@ 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
   */
@@ -521,7 +521,7 @@ interface HeadResult {
 /**
 * Error codes for DurableStreamError.
 */
-type DurableStreamErrorCode = `NOT_FOUND` | `CONFLICT_SEQ` | `CONFLICT_EXISTS` | `BAD_REQUEST` | `BUSY` | `SSE_NOT_SUPPORTED` | `UNAUTHORIZED` | `FORBIDDEN` | `RATE_LIMITED` | `ALREADY_CONSUMED` | `ALREADY_CLOSED` | `UNKNOWN`;
+type DurableStreamErrorCode = `NOT_FOUND` | `CONFLICT_SEQ` | `CONFLICT_EXISTS` | `BAD_REQUEST` | `BUSY` | `SSE_NOT_SUPPORTED` | `UNAUTHORIZED` | `FORBIDDEN` | `RATE_LIMITED` | `ALREADY_CONSUMED` | `ALREADY_CLOSED` | `PARSE_ERROR` | `UNKNOWN`;
 /**
 * Options returned from onError handler to retry with modified params/headers.
 * Following the Electric client pattern.
@@ -638,33 +638,33 @@ 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;
   /**
   * 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>;
   /**
@@ -692,18 +692,27 @@ 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>) => () => void;
+  subscribeJson: <T = TJson>(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>) => () => void;
+  subscribeBytes: (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;
   /**
   * Cancel the underlying session (abort HTTP, close SSE, stop long-polls).
   */
@@ -800,7 +809,7 @@ interface IdempotentAppendResult {
 *   url,
 *   auth,
 *   offset: savedOffset,
-*   live: "auto",
+*   live: true,
 * })
 * live.subscribeJson(async (batch) => {
 *   for (const item of batch.items) {
@@ -853,7 +862,7 @@ 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 }>();
@@ -931,22 +940,26 @@ declare 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]));
   * ```
   */
-  append(body: BodyInit | Uint8Array | string | unknown, opts?: AppendOptions): Promise<void>;
+  append(body: Uint8Array | string | Promise<Uint8Array | string>, opts?: AppendOptions): Promise<void>;
   /**
   * Append a streaming body to the stream.
   *
@@ -986,6 +999,11 @@ declare 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
@@ -995,9 +1013,19 @@ declare 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>;
+  writable(opts?: Pick<IdempotentProducerOptions, `lingerMs` | `maxBatchBytes` | `onError`> & {
+    producerId?: string;
+    signal?: AbortSignal;
+  }): WritableStream<Uint8Array | string>;
   /**
   * Start a fetch-like streaming session against this handle's URL/headers/params.
   * The first request is made inside this method; it resolves when we have
@@ -1132,12 +1160,22 @@ declare class IdempotentProducer {
   * Errors are reported via onError callback if configured. Use flush() to
   * wait for all pending messages to be sent.
   *
-  * For JSON streams, pass native objects (which will be serialized internally).
+  * For JSON streams, pass pre-serialized JSON strings.
   * For byte streams, pass string or Uint8Array.
   *
-  * @param body - Data to append (object for JSON streams, string or Uint8Array for byte streams)
+  * @param body - Data to append (string or Uint8Array)
+  *
+  * @example
+  * ```typescript
+  * // JSON stream
+  * producer.append(JSON.stringify({ message: "hello" }));
+  *
+  * // Byte stream
+  * producer.append("raw text data");
+  * producer.append(new Uint8Array([1, 2, 3]));
+  * ```
   */
-  append(body: Uint8Array | string | unknown): void;
+  append(body: Uint8Array | string): void;
   /**
   * Send any pending batch immediately and wait for all in-flight batches.
   *