@durable-streams/client 0.1.5 → 0.2.1

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
   */
@@ -306,6 +306,11 @@ 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;
 }
 /**
 * A batch of parsed JSON items with metadata.
@@ -415,6 +420,17 @@ 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;
 }
 /**
 * Options for appending data to a stream.
@@ -455,6 +471,37 @@ interface AppendOptions {
   producerSeq?: number;
 }
 /**
+* Result of a close operation.
+*/
+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.
+*/
+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
 */
@@ -512,6 +559,11 @@ interface HeadResult {
   * Cache-Control header value.
   */
   cacheControl?: string;
+  /**
+  * Whether the stream is closed.
+  * When true, no further appends are permitted.
+  */
+  streamClosed: boolean;
 }
 /**
 * Metadata extracted from a stream response.
@@ -521,7 +573,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` | `STREAM_CLOSED` | `UNKNOWN`;
 /**
 * Options returned from onError handler to retry with modified params/headers.
 * Following the Electric client pattern.
@@ -638,33 +690,45 @@ 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;
   /**
   * 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 +756,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 +873,7 @@ interface IdempotentAppendResult {
 *   url,
 *   auth,
 *   offset: savedOffset,
-*   live: "auto",
+*   live: true,
 * })
 * live.subscribeJson(async (batch) => {
 *   for (const item of batch.items) {
@@ -853,7 +926,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 }>();
@@ -925,28 +998,54 @@ declare class DurableStream {
     signal?: AbortSignal;
   }): Promise<void>;
   /**
+  * 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
+  */
+  close(opts?: CloseOptions): Promise<CloseResult>;
+  /**
   * Append a single payload to the stream.
   *
   * When batching is enabled (default), multiple append() calls made while
   * 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 +1085,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 +1099,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 +1246,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.
   *
@@ -1145,11 +1269,33 @@ declare class IdempotentProducer {
   */
   flush(): Promise<void>;
   /**
-  * Flush pending messages and close the producer.
+  * Stop the producer without closing the underlying stream.
+  *
+  * Use this when you want to:
+  * - Hand off writing to another producer
+  * - Keep the stream open for future writes
+  * - Stop this producer but not signal EOF to readers
   *
-  * After calling close(), further append() calls will throw.
+  * Flushes any pending messages before detaching.
+  * After calling detach(), further append() calls will throw.
   */
-  close(): Promise<void>;
+  detach(): Promise<void>;
+  /**
+  * Flush pending messages and close the underlying stream (EOF).
+  *
+  * This is the typical way to end a producer session. It:
+  * 1. Flushes all pending messages
+  * 2. Optionally appends a final message
+  * 3. Closes the stream (no further appends permitted)
+  *
+  * **Idempotent**: Unlike `DurableStream.close({ body })`, this method is
+  * idempotent even with a final message because it uses producer headers
+  * for deduplication. Safe to retry on network failures.
+  *
+  * @param finalMessage - Optional final message to append atomically with close
+  * @returns CloseResult with the final offset
+  */
+  close(finalMessage?: Uint8Array | string): Promise<CloseResult>;
   /**
   * Increment epoch and reset sequence.
   *
@@ -1230,6 +1376,19 @@ declare class MissingStreamUrlError extends Error {
   constructor();
 }
 /**
+* Error thrown when attempting to append to a closed stream.
+*/
+declare class StreamClosedError extends DurableStreamError {
+  readonly code: "STREAM_CLOSED";
+  readonly status = 409;
+  readonly streamClosed: true;
+  /**
+  * The final offset of the stream, if available from the response.
+  */
+  readonly finalOffset?: string;
+  constructor(url?: string, finalOffset?: string);
+}
+/**
 * Error thrown when signal option is invalid.
 */
 declare class InvalidSignalError extends Error {
@@ -1259,6 +1418,11 @@ declare const STREAM_CURSOR_HEADER = "Stream-Cursor";
 */
 declare const STREAM_UP_TO_DATE_HEADER = "Stream-Up-To-Date";
 /**
+* Response/request header indicating stream is closed (EOF).
+* When present with value "true", the stream is permanently closed.
+*/
+declare const STREAM_CLOSED_HEADER = "Stream-Closed";
+/**
 * Request header for writer coordination sequence.
 * Monotonic, lexicographic. If lower than last appended seq -> 409 Conflict.
 */
@@ -1307,13 +1471,17 @@ declare const LIVE_QUERY_PARAM = "live";
 */
 declare const CURSOR_QUERY_PARAM = "cursor";
 /**
-* SSE control event field for the next offset.
-* Note: Different from HTTP header name (camelCase vs Header-Case).
+* Response header indicating SSE data encoding (e.g., base64 for binary streams).
 */
 
 /**
-* Content types that support SSE mode.
-* SSE is only valid for text/* or application/json streams.
+* SSE control event field for stream closed state.
+* Note: Different from HTTP header name (camelCase vs Header-Case).
+*/
+declare const SSE_CLOSED_FIELD = "streamClosed";
+/**
+* Content types that are natively compatible with SSE (UTF-8 text).
+* Binary content types are also supported via automatic base64 encoding.
 */
 declare const SSE_COMPATIBLE_CONTENT_TYPES: ReadonlyArray<string>;
 /**
@@ -1322,4 +1490,4 @@ declare const SSE_COMPATIBLE_CONTENT_TYPES: ReadonlyArray<string>;
 declare const DURABLE_STREAM_PROTOCOL_QUERY_PARAMS: Array<string>;
 
 //#endregion
-export { AppendOptions, BackoffDefaults, BackoffOptions, ByteChunk, CURSOR_QUERY_PARAM, CreateOptions, DURABLE_STREAM_PROTOCOL_QUERY_PARAMS, DurableStream, DurableStreamError, DurableStreamErrorCode, DurableStreamOptions, FetchBackoffAbortError, FetchError, HeadResult, HeadersRecord, IdempotentAppendResult, IdempotentProducer, IdempotentProducerOptions, InvalidSignalError, JsonBatch, JsonBatchMeta, LIVE_QUERY_PARAM, LegacyLiveMode, LiveMode, MaybePromise, MissingStreamUrlError, OFFSET_QUERY_PARAM, Offset, PRODUCER_EPOCH_HEADER, PRODUCER_EXPECTED_SEQ_HEADER, PRODUCER_ID_HEADER, PRODUCER_RECEIVED_SEQ_HEADER, PRODUCER_SEQ_HEADER, ParamsRecord, ReadOptions, ReadableStreamAsyncIterable, RetryOpts, SSEResilienceOptions, SSE_COMPATIBLE_CONTENT_TYPES, STREAM_CURSOR_HEADER, STREAM_EXPIRES_AT_HEADER, STREAM_OFFSET_HEADER, STREAM_SEQ_HEADER, STREAM_TTL_HEADER, STREAM_UP_TO_DATE_HEADER, SequenceGapError, StaleEpochError, StreamErrorHandler, StreamHandleOptions, StreamOptions, StreamResponse, TextChunk, _resetHttpWarningForTesting, asAsyncIterableReadableStream, createFetchWithBackoff, createFetchWithConsumedBody, stream, warnIfUsingHttpInBrowser };
+export { AppendOptions, BackoffDefaults, BackoffOptions, ByteChunk, CURSOR_QUERY_PARAM, CloseOptions, CloseResult, CreateOptions, DURABLE_STREAM_PROTOCOL_QUERY_PARAMS, DurableStream, DurableStreamError, DurableStreamErrorCode, DurableStreamOptions, FetchBackoffAbortError, FetchError, HeadResult, HeadersRecord, IdempotentAppendResult, IdempotentProducer, IdempotentProducerOptions, InvalidSignalError, JsonBatch, JsonBatchMeta, LIVE_QUERY_PARAM, LegacyLiveMode, LiveMode, MaybePromise, MissingStreamUrlError, OFFSET_QUERY_PARAM, Offset, PRODUCER_EPOCH_HEADER, PRODUCER_EXPECTED_SEQ_HEADER, PRODUCER_ID_HEADER, PRODUCER_RECEIVED_SEQ_HEADER, PRODUCER_SEQ_HEADER, ParamsRecord, ReadOptions, ReadableStreamAsyncIterable, RetryOpts, SSEResilienceOptions, SSE_CLOSED_FIELD, SSE_COMPATIBLE_CONTENT_TYPES, STREAM_CLOSED_HEADER, STREAM_CURSOR_HEADER, STREAM_EXPIRES_AT_HEADER, STREAM_OFFSET_HEADER, STREAM_SEQ_HEADER, STREAM_TTL_HEADER, STREAM_UP_TO_DATE_HEADER, SequenceGapError, StaleEpochError, StreamClosedError, StreamErrorHandler, StreamHandleOptions, StreamOptions, StreamResponse, TextChunk, _resetHttpWarningForTesting, asAsyncIterableReadableStream, createFetchWithBackoff, createFetchWithConsumedBody, stream, warnIfUsingHttpInBrowser };