@durable-streams/client 0.2.0 → 0.2.1

package/dist/index.d.cts

@@ -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` | `PARSE_ERROR` | `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.
@@ -652,6 +704,18 @@ interface StreamResponse<TJson = unknown> {
   */
   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: true`, signals the session to stop after upToDate.
   */
@@ -934,6 +998,28 @@ 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
@@ -1183,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.
   *
@@ -1268,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 {
@@ -1297,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.
 */
@@ -1345,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>;
 /**
@@ -1360,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 };

package/dist/index.d.ts

@@ -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` | `PARSE_ERROR` | `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.
@@ -652,6 +704,18 @@ interface StreamResponse<TJson = unknown> {
   */
   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: true`, signals the session to stop after upToDate.
   */
@@ -934,6 +998,28 @@ 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
@@ -1183,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.
   *
@@ -1268,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 {
@@ -1297,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.
 */
@@ -1345,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>;
 /**
@@ -1360,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 };