@durable-streams/client 0.2.0 → 0.2.2

package/dist/index.cjs

@@ -46,6 +46,11 @@ const STREAM_CURSOR_HEADER = `Stream-Cursor`;
 */
 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.
+*/
+const STREAM_CLOSED_HEADER = `Stream-Closed`;
+/**
 * Request header for writer coordination sequence.
 * Monotonic, lexicographic. If lower than last appended seq -> 409 Conflict.
 */
@@ -94,8 +99,17 @@ const LIVE_QUERY_PARAM = `live`;
 */
 const CURSOR_QUERY_PARAM = `cursor`;
 /**
-* Content types that support SSE mode.
-* SSE is only valid for text/* or application/json streams.
+* Response header indicating SSE data encoding (e.g., base64 for binary streams).
+*/
+const STREAM_SSE_DATA_ENCODING_HEADER = `stream-sse-data-encoding`;
+/**
+* SSE control event field for stream closed state.
+* Note: Different from HTTP header name (camelCase vs Header-Case).
+*/
+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.
 */
 const SSE_COMPATIBLE_CONTENT_TYPES = [`text/`, `application/json`];
 /**
@@ -225,6 +239,23 @@ var MissingStreamUrlError = class extends Error {
 	}
 };
 /**
+* Error thrown when attempting to append to a closed stream.
+*/
+var StreamClosedError = class extends DurableStreamError {
+	code = `STREAM_CLOSED`;
+	status = 409;
+	streamClosed = true;
+	/**
+	* The final offset of the stream, if available from the response.
+	*/
+	finalOffset;
+	constructor(url, finalOffset) {
+		super(`Cannot append to closed stream`, `STREAM_CLOSED`, 409, url);
+		this.name = `StreamClosedError`;
+		this.finalOffset = finalOffset;
+	}
+};
+/**
 * Error thrown when signal option is invalid.
 */
 var InvalidSignalError = class extends Error {
@@ -504,7 +535,8 @@ async function* parseSSEStream(stream$1, signal) {
 							type: `control`,
 							streamNextOffset: control.streamNextOffset,
 							streamCursor: control.streamCursor,
-							upToDate: control.upToDate
+							upToDate: control.upToDate,
+							streamClosed: control.streamClosed
 						};
 					} catch (err) {
 						const preview = dataStr.length > 100 ? dataStr.slice(0, 100) + `...` : dataStr;
@@ -512,8 +544,10 @@ async function* parseSSEStream(stream$1, signal) {
 					}
 				}
 				currentEvent = { data: [] };
-			} else if (line.startsWith(`event:`)) currentEvent.type = line.slice(6).trim();
-			else if (line.startsWith(`data:`)) {
+			} else if (line.startsWith(`event:`)) {
+				const eventType = line.slice(6);
+				currentEvent.type = eventType.startsWith(` `) ? eventType.slice(1) : eventType;
+			} else if (line.startsWith(`data:`)) {
 				const content = line.slice(5);
 				currentEvent.data.push(content.startsWith(` `) ? content.slice(1) : content);
 			}
@@ -532,7 +566,8 @@ async function* parseSSEStream(stream$1, signal) {
 					type: `control`,
 					streamNextOffset: control.streamNextOffset,
 					streamCursor: control.streamCursor,
-					upToDate: control.upToDate
+					upToDate: control.upToDate,
+					streamClosed: control.streamClosed
 				};
 			} catch (err) {
 				const preview = dataStr.length > 100 ? dataStr.slice(0, 100) + `...` : dataStr;
@@ -544,6 +579,207 @@ async function* parseSSEStream(stream$1, signal) {
 	}
 }
 
+//#endregion
+//#region src/stream-response-state.ts
+/**
+* Abstract base class for stream response state.
+* All state transitions return new immutable state objects.
+*/
+var StreamResponseState = class {
+	shouldContinueLive(stopAfterUpToDate, liveMode) {
+		if (stopAfterUpToDate && this.upToDate) return false;
+		if (liveMode === false) return false;
+		if (this.streamClosed) return false;
+		return true;
+	}
+};
+/**
+* State for long-poll mode. shouldUseSse() returns false.
+*/
+var LongPollState = class LongPollState extends StreamResponseState {
+	offset;
+	cursor;
+	upToDate;
+	streamClosed;
+	constructor(fields) {
+		super();
+		this.offset = fields.offset;
+		this.cursor = fields.cursor;
+		this.upToDate = fields.upToDate;
+		this.streamClosed = fields.streamClosed;
+	}
+	shouldUseSse() {
+		return false;
+	}
+	withResponseMetadata(update) {
+		return new LongPollState({
+			offset: update.offset ?? this.offset,
+			cursor: update.cursor ?? this.cursor,
+			upToDate: update.upToDate,
+			streamClosed: this.streamClosed || update.streamClosed
+		});
+	}
+	withSSEControl(event) {
+		const streamClosed = this.streamClosed || (event.streamClosed ?? false);
+		return new LongPollState({
+			offset: event.streamNextOffset,
+			cursor: event.streamCursor || this.cursor,
+			upToDate: event.streamClosed ?? false ? true : event.upToDate ?? this.upToDate,
+			streamClosed
+		});
+	}
+	pause() {
+		return new PausedState(this);
+	}
+};
+/**
+* State for SSE mode. shouldUseSse() returns true.
+* Tracks SSE connection resilience (short connection detection).
+*/
+var SSEState = class SSEState extends StreamResponseState {
+	offset;
+	cursor;
+	upToDate;
+	streamClosed;
+	consecutiveShortConnections;
+	connectionStartTime;
+	constructor(fields) {
+		super();
+		this.offset = fields.offset;
+		this.cursor = fields.cursor;
+		this.upToDate = fields.upToDate;
+		this.streamClosed = fields.streamClosed;
+		this.consecutiveShortConnections = fields.consecutiveShortConnections ?? 0;
+		this.connectionStartTime = fields.connectionStartTime;
+	}
+	shouldUseSse() {
+		return true;
+	}
+	withResponseMetadata(update) {
+		return new SSEState({
+			offset: update.offset ?? this.offset,
+			cursor: update.cursor ?? this.cursor,
+			upToDate: update.upToDate,
+			streamClosed: this.streamClosed || update.streamClosed,
+			consecutiveShortConnections: this.consecutiveShortConnections,
+			connectionStartTime: this.connectionStartTime
+		});
+	}
+	withSSEControl(event) {
+		const streamClosed = this.streamClosed || (event.streamClosed ?? false);
+		return new SSEState({
+			offset: event.streamNextOffset,
+			cursor: event.streamCursor || this.cursor,
+			upToDate: event.streamClosed ?? false ? true : event.upToDate ?? this.upToDate,
+			streamClosed,
+			consecutiveShortConnections: this.consecutiveShortConnections,
+			connectionStartTime: this.connectionStartTime
+		});
+	}
+	startConnection(now) {
+		return new SSEState({
+			offset: this.offset,
+			cursor: this.cursor,
+			upToDate: this.upToDate,
+			streamClosed: this.streamClosed,
+			consecutiveShortConnections: this.consecutiveShortConnections,
+			connectionStartTime: now
+		});
+	}
+	handleConnectionEnd(now, wasAborted, config) {
+		if (this.connectionStartTime === void 0) return {
+			action: `healthy`,
+			state: this
+		};
+		const duration = now - this.connectionStartTime;
+		if (duration < config.minConnectionDuration && !wasAborted) {
+			const newCount = this.consecutiveShortConnections + 1;
+			if (newCount >= config.maxShortConnections) return {
+				action: `fallback`,
+				state: new LongPollState({
+					offset: this.offset,
+					cursor: this.cursor,
+					upToDate: this.upToDate,
+					streamClosed: this.streamClosed
+				})
+			};
+			return {
+				action: `reconnect`,
+				state: new SSEState({
+					offset: this.offset,
+					cursor: this.cursor,
+					upToDate: this.upToDate,
+					streamClosed: this.streamClosed,
+					consecutiveShortConnections: newCount,
+					connectionStartTime: this.connectionStartTime
+				}),
+				backoffAttempt: newCount
+			};
+		}
+		if (duration >= config.minConnectionDuration) return {
+			action: `healthy`,
+			state: new SSEState({
+				offset: this.offset,
+				cursor: this.cursor,
+				upToDate: this.upToDate,
+				streamClosed: this.streamClosed,
+				consecutiveShortConnections: 0,
+				connectionStartTime: this.connectionStartTime
+			})
+		};
+		return {
+			action: `healthy`,
+			state: this
+		};
+	}
+	pause() {
+		return new PausedState(this);
+	}
+};
+/**
+* Paused state wrapper. Delegates all sync field access to the inner state.
+* resume() returns the wrapped state unchanged (identity preserved).
+*/
+var PausedState = class PausedState extends StreamResponseState {
+	#inner;
+	constructor(inner) {
+		super();
+		this.#inner = inner;
+	}
+	get offset() {
+		return this.#inner.offset;
+	}
+	get cursor() {
+		return this.#inner.cursor;
+	}
+	get upToDate() {
+		return this.#inner.upToDate;
+	}
+	get streamClosed() {
+		return this.#inner.streamClosed;
+	}
+	shouldUseSse() {
+		return this.#inner.shouldUseSse();
+	}
+	withResponseMetadata(update) {
+		const newInner = this.#inner.withResponseMetadata(update);
+		return new PausedState(newInner);
+	}
+	withSSEControl(event) {
+		const newInner = this.#inner.withSSEControl(event);
+		return new PausedState(newInner);
+	}
+	pause() {
+		return this;
+	}
+	resume() {
+		return {
+			state: this.#inner,
+			justResumed: true
+		};
+	}
+};
+
 //#endregion
 //#region src/response.ts
 /**
@@ -563,9 +799,7 @@ var StreamResponseImpl = class {
 	#statusText;
 	#ok;
 	#isLoading;
-	#offset;
-	#cursor;
-	#upToDate;
+	#syncState;
 	#isJsonMode;
 	#abortController;
 	#fetchNext;
@@ -580,20 +814,21 @@ var StreamResponseImpl = class {
 	#unsubscribeFromVisibilityChanges;
 	#pausePromise;
 	#pauseResolve;
-	#justResumedFromPause = false;
 	#sseResilience;
-	#lastSSEConnectionStartTime;
-	#consecutiveShortSSEConnections = 0;
-	#sseFallbackToLongPoll = false;
+	#encoding;
 	#responseStream;
 	constructor(config) {
 		this.url = config.url;
 		this.contentType = config.contentType;
 		this.live = config.live;
 		this.startOffset = config.startOffset;
-		this.#offset = config.initialOffset;
-		this.#cursor = config.initialCursor;
-		this.#upToDate = config.initialUpToDate;
+		const syncFields = {
+			offset: config.initialOffset,
+			cursor: config.initialCursor,
+			upToDate: config.initialUpToDate,
+			streamClosed: config.initialStreamClosed
+		};
+		this.#syncState = config.startSSE ? new SSEState(syncFields) : new LongPollState(syncFields);
 		this.#headers = config.firstResponse.headers;
 		this.#status = config.firstResponse.status;
 		this.#statusText = config.firstResponse.statusText;
@@ -610,6 +845,7 @@ var StreamResponseImpl = class {
 			backoffMaxDelay: config.sseResilience?.backoffMaxDelay ?? 5e3,
 			logWarnings: config.sseResilience?.logWarnings ?? true
 		};
+		this.#encoding = config.encoding;
 		this.#closed = new Promise((resolve, reject) => {
 			this.#closedResolve = resolve;
 			this.#closedReject = reject;
@@ -649,6 +885,7 @@ var StreamResponseImpl = class {
 	#pause() {
 		if (this.#state === `active`) {
 			this.#state = `pause-requested`;
+			this.#syncState = this.#syncState.pause();
 			this.#pausePromise = new Promise((resolve) => {
 				this.#pauseResolve = resolve;
 			});
@@ -662,8 +899,8 @@ var StreamResponseImpl = class {
 	#resume() {
 		if (this.#state === `paused` || this.#state === `pause-requested`) {
 			if (this.#abortController.signal.aborted) return;
+			if (this.#syncState instanceof PausedState) this.#syncState = this.#syncState.resume().state;
 			this.#state = `active`;
-			this.#justResumedFromPause = true;
 			this.#pauseResolve?.();
 			this.#pausePromise = void 0;
 			this.#pauseResolve = void 0;
@@ -685,13 +922,16 @@ var StreamResponseImpl = class {
 		return this.#isLoading;
 	}
 	get offset() {
-		return this.#offset;
+		return this.#syncState.offset;
 	}
 	get cursor() {
-		return this.#cursor;
+		return this.#syncState.cursor;
 	}
 	get upToDate() {
-		return this.#upToDate;
+		return this.#syncState.upToDate;
+	}
+	get streamClosed() {
+		return this.#syncState.streamClosed;
 	}
 	#ensureJsonMode() {
 		if (!this.#isJsonMode) throw new DurableStreamError(`JSON methods are only valid for JSON-mode streams. Content-Type is "${this.contentType}" and json hint was not set.`, `BAD_REQUEST`);
@@ -714,105 +954,64 @@ var StreamResponseImpl = class {
 	}
 	/**
 	* Determine if we should continue with live updates based on live mode
-	* and whether we've received upToDate.
+	* and whether we've received upToDate or streamClosed.
 	*/
 	#shouldContinueLive() {
-		if (this.#stopAfterUpToDate && this.upToDate) return false;
-		if (this.live === false) return false;
-		return true;
+		return this.#syncState.shouldContinueLive(this.#stopAfterUpToDate, this.live);
 	}
 	/**
 	* Update state from response headers.
 	*/
 	#updateStateFromResponse(response) {
-		const offset = response.headers.get(STREAM_OFFSET_HEADER);
-		if (offset) this.#offset = offset;
-		const cursor = response.headers.get(STREAM_CURSOR_HEADER);
-		if (cursor) this.#cursor = cursor;
-		this.#upToDate = response.headers.has(STREAM_UP_TO_DATE_HEADER);
+		this.#syncState = this.#syncState.withResponseMetadata({
+			offset: response.headers.get(STREAM_OFFSET_HEADER) || void 0,
+			cursor: response.headers.get(STREAM_CURSOR_HEADER) || void 0,
+			upToDate: response.headers.has(STREAM_UP_TO_DATE_HEADER),
+			streamClosed: response.headers.get(STREAM_CLOSED_HEADER)?.toLowerCase() === `true`
+		});
 		this.#headers = response.headers;
 		this.#status = response.status;
 		this.#statusText = response.statusText;
 		this.#ok = response.ok;
 	}
 	/**
-	* Extract stream metadata from Response headers.
-	* Used by subscriber APIs to get the correct offset/cursor/upToDate for each
-	* specific Response, rather than reading from `this` which may be stale due to
-	* ReadableStream prefetching or timing issues.
-	*/
-	#getMetadataFromResponse(response) {
-		const offset = response.headers.get(STREAM_OFFSET_HEADER);
-		const cursor = response.headers.get(STREAM_CURSOR_HEADER);
-		const upToDate = response.headers.has(STREAM_UP_TO_DATE_HEADER);
-		return {
-			offset: offset ?? this.offset,
-			cursor: cursor ?? this.cursor,
-			upToDate
-		};
-	}
-	/**
-	* Create a synthetic Response from SSE data with proper headers.
-	* Includes offset/cursor/upToDate in headers so subscribers can read them.
-	*/
-	#createSSESyntheticResponse(data, offset, cursor, upToDate) {
-		const headers = {
-			"content-type": this.contentType ?? `application/json`,
-			[STREAM_OFFSET_HEADER]: String(offset)
-		};
-		if (cursor) headers[STREAM_CURSOR_HEADER] = cursor;
-		if (upToDate) headers[STREAM_UP_TO_DATE_HEADER] = `true`;
-		return new Response(data, {
-			status: 200,
-			headers
-		});
-	}
-	/**
 	* Update instance state from an SSE control event.
 	*/
 	#updateStateFromSSEControl(controlEvent) {
-		this.#offset = controlEvent.streamNextOffset;
-		if (controlEvent.streamCursor) this.#cursor = controlEvent.streamCursor;
-		if (controlEvent.upToDate !== void 0) this.#upToDate = controlEvent.upToDate;
+		this.#syncState = this.#syncState.withSSEControl(controlEvent);
 	}
 	/**
 	* Mark the start of an SSE connection for duration tracking.
+	* If the state is not SSEState (e.g., auto-detected SSE from content-type),
+	* transitions to SSEState first.
 	*/
 	#markSSEConnectionStart() {
-		this.#lastSSEConnectionStartTime = Date.now();
-	}
-	/**
-	* Handle SSE connection end - check duration and manage fallback state.
-	* Returns a delay to wait before reconnecting, or null if should not reconnect.
-	*/
-	async #handleSSEConnectionEnd() {
-		if (this.#lastSSEConnectionStartTime === void 0) return 0;
-		const connectionDuration = Date.now() - this.#lastSSEConnectionStartTime;
-		const wasAborted = this.#abortController.signal.aborted;
-		if (connectionDuration < this.#sseResilience.minConnectionDuration && !wasAborted) {
-			this.#consecutiveShortSSEConnections++;
-			if (this.#consecutiveShortSSEConnections >= this.#sseResilience.maxShortConnections) {
-				this.#sseFallbackToLongPoll = true;
-				if (this.#sseResilience.logWarnings) console.warn("[Durable Streams] SSE connections are closing immediately (possibly due to proxy buffering or misconfiguration). Falling back to long polling. Your proxy must support streaming SSE responses (not buffer the complete response). Configuration: Nginx add 'X-Accel-Buffering: no', Caddy add 'flush_interval -1' to reverse_proxy.");
-				return null;
-			} else {
-				const maxDelay = Math.min(this.#sseResilience.backoffMaxDelay, this.#sseResilience.backoffBaseDelay * Math.pow(2, this.#consecutiveShortSSEConnections));
-				const delayMs = Math.floor(Math.random() * maxDelay);
-				await new Promise((resolve) => setTimeout(resolve, delayMs));
-				return delayMs;
-			}
-		} else if (connectionDuration >= this.#sseResilience.minConnectionDuration) this.#consecutiveShortSSEConnections = 0;
-		return 0;
+		if (!(this.#syncState instanceof SSEState)) this.#syncState = new SSEState({
+			offset: this.#syncState.offset,
+			cursor: this.#syncState.cursor,
+			upToDate: this.#syncState.upToDate,
+			streamClosed: this.#syncState.streamClosed
+		});
+		this.#syncState = this.#syncState.startConnection(Date.now());
 	}
 	/**
 	* Try to reconnect SSE and return the new iterator, or null if reconnection
 	* is not possible or fails.
 	*/
 	async #trySSEReconnect() {
-		if (this.#sseFallbackToLongPoll) return null;
+		if (!this.#syncState.shouldUseSse()) return null;
 		if (!this.#shouldContinueLive() || !this.#startSSE) return null;
-		const delayOrNull = await this.#handleSSEConnectionEnd();
-		if (delayOrNull === null) return null;
+		const result = this.#syncState.handleConnectionEnd(Date.now(), this.#abortController.signal.aborted, this.#sseResilience);
+		this.#syncState = result.state;
+		if (result.action === `fallback`) {
+			if (this.#sseResilience.logWarnings) console.warn("[Durable Streams] SSE connections are closing immediately (possibly due to proxy buffering or misconfiguration). Falling back to long polling. Your proxy must support streaming SSE responses (not buffer the complete response). Configuration: Nginx add 'X-Accel-Buffering: no', Caddy add 'flush_interval -1' to reverse_proxy.");
+			return null;
+		}
+		if (result.action === `reconnect`) {
+			const maxDelay = Math.min(this.#sseResilience.backoffMaxDelay, this.#sseResilience.backoffBaseDelay * Math.pow(2, result.backoffAttempt));
+			const delayMs = Math.floor(Math.random() * maxDelay);
+			await new Promise((resolve) => setTimeout(resolve, delayMs));
+		}
 		this.#markSSEConnectionStart();
 		this.#requestAbortController = new AbortController();
 		const newSSEResponse = await this.#startSSE(this.offset, this.cursor, this.#requestAbortController.signal);
@@ -846,19 +1045,29 @@ var StreamResponseImpl = class {
 		}
 		if (event.type === `data`) return this.#processSSEDataEvent(event.data, sseEventIterator);
 		this.#updateStateFromSSEControl(event);
+		if (event.upToDate) {
+			const response = createSSESyntheticResponse(``, event.streamNextOffset, event.streamCursor, true, event.streamClosed ?? false, this.contentType, this.#encoding);
+			return {
+				type: `response`,
+				response
+			};
+		}
 		return { type: `continue` };
 	}
 	/**
 	* Process an SSE data event by waiting for its corresponding control event.
 	* In SSE protocol, control events come AFTER data events.
 	* Multiple data events may arrive before a single control event - we buffer them.
+	*
+	* For base64 mode, each data event is independently base64 encoded, so we
+	* collect them as an array and decode each separately.
 	*/
 	async #processSSEDataEvent(pendingData, sseEventIterator) {
-		let bufferedData = pendingData;
+		const bufferedDataParts = [pendingData];
 		while (true) {
 			const { done: controlDone, value: controlEvent } = await sseEventIterator.next();
 			if (controlDone) {
-				const response = this.#createSSESyntheticResponse(bufferedData, this.offset, this.cursor, this.upToDate);
+				const response = createSSESyntheticResponseFromParts(bufferedDataParts, this.offset, this.cursor, this.upToDate, this.streamClosed, this.contentType, this.#encoding, this.#isJsonMode);
 				try {
 					const newIterator = await this.#trySSEReconnect();
 					return {
@@ -875,13 +1084,13 @@ var StreamResponseImpl = class {
 			}
 			if (controlEvent.type === `control`) {
 				this.#updateStateFromSSEControl(controlEvent);
-				const response = this.#createSSESyntheticResponse(bufferedData, controlEvent.streamNextOffset, controlEvent.streamCursor, controlEvent.upToDate ?? false);
+				const response = createSSESyntheticResponseFromParts(bufferedDataParts, controlEvent.streamNextOffset, controlEvent.streamCursor, controlEvent.upToDate ?? false, controlEvent.streamClosed ?? false, this.contentType, this.#encoding, this.#isJsonMode);
 				return {
 					type: `response`,
 					response
 				};
 			}
-			bufferedData += controlEvent.data;
+			bufferedDataParts.push(controlEvent.data);
 		}
 	}
 	/**
@@ -953,6 +1162,7 @@ var StreamResponseImpl = class {
 						}
 					}
 					if (this.#shouldContinueLive()) {
+						let resumingFromPause = false;
 						if (this.#state === `pause-requested` || this.#state === `paused`) {
 							this.#state = `paused`;
 							if (this.#pausePromise) await this.#pausePromise;
@@ -961,14 +1171,13 @@ var StreamResponseImpl = class {
 								controller.close();
 								return;
 							}
+							resumingFromPause = true;
 						}
 						if (this.#abortController.signal.aborted) {
 							this.#markClosed();
 							controller.close();
 							return;
 						}
-						const resumingFromPause = this.#justResumedFromPause;
-						this.#justResumedFromPause = false;
 						this.#requestAbortController = new AbortController();
 						const response = await this.#fetchNext(this.offset, this.cursor, this.#requestAbortController.signal, resumingFromPause);
 						this.#updateStateFromResponse(response);
@@ -1134,23 +1343,28 @@ var StreamResponseImpl = class {
 					controller.enqueue(pendingItems.shift());
 					return;
 				}
-				const { done, value: response } = await reader.read();
-				if (done) {
-					this.#markClosed();
-					controller.close();
-					return;
-				}
-				const text = await response.text();
-				const content = text.trim() || `[]`;
-				let parsed;
-				try {
-					parsed = JSON.parse(content);
-				} catch (err) {
-					const preview = content.length > 100 ? content.slice(0, 100) + `...` : content;
-					throw new DurableStreamError(`Failed to parse JSON response: ${err instanceof Error ? err.message : String(err)}. Data: ${preview}`, `PARSE_ERROR`);
+				let result = await reader.read();
+				while (!result.done) {
+					const response = result.value;
+					const text = await response.text();
+					const content = text.trim() || `[]`;
+					let parsed;
+					try {
+						parsed = JSON.parse(content);
+					} catch (err) {
+						const preview = content.length > 100 ? content.slice(0, 100) + `...` : content;
+						throw new DurableStreamError(`Failed to parse JSON response: ${err instanceof Error ? err.message : String(err)}. Data: ${preview}`, `PARSE_ERROR`);
+					}
+					pendingItems = Array.isArray(parsed) ? parsed : [parsed];
+					if (pendingItems.length > 0) {
+						controller.enqueue(pendingItems.shift());
+						return;
+					}
+					result = await reader.read();
 				}
-				pendingItems = Array.isArray(parsed) ? parsed : [parsed];
-				if (pendingItems.length > 0) controller.enqueue(pendingItems.shift());
+				this.#markClosed();
+				controller.close();
+				return;
 			},
 			cancel: () => {
 				reader.releaseLock();
@@ -1184,7 +1398,7 @@ var StreamResponseImpl = class {
 				while (!result.done) {
 					if (abortController.signal.aborted) break;
 					const response = result.value;
-					const { offset, cursor, upToDate } = this.#getMetadataFromResponse(response);
+					const { offset, cursor, upToDate, streamClosed } = getMetadataFromResponse(response, this.offset, this.cursor, this.streamClosed);
 					const text = await response.text();
 					const content = text.trim() || `[]`;
 					let parsed;
@@ -1199,7 +1413,8 @@ var StreamResponseImpl = class {
 						items,
 						offset,
 						cursor,
-						upToDate
+						upToDate,
+						streamClosed
 					});
 					result = await reader.read();
 				}
@@ -1229,13 +1444,14 @@ var StreamResponseImpl = class {
 				while (!result.done) {
 					if (abortController.signal.aborted) break;
 					const response = result.value;
-					const { offset, cursor, upToDate } = this.#getMetadataFromResponse(response);
+					const { offset, cursor, upToDate, streamClosed } = getMetadataFromResponse(response, this.offset, this.cursor, this.streamClosed);
 					const buffer = await response.arrayBuffer();
 					await subscriber({
 						data: new Uint8Array(buffer),
 						offset,
 						cursor,
-						upToDate
+						upToDate,
+						streamClosed
 					});
 					result = await reader.read();
 				}
@@ -1265,13 +1481,14 @@ var StreamResponseImpl = class {
 				while (!result.done) {
 					if (abortController.signal.aborted) break;
 					const response = result.value;
-					const { offset, cursor, upToDate } = this.#getMetadataFromResponse(response);
+					const { offset, cursor, upToDate, streamClosed } = getMetadataFromResponse(response, this.offset, this.cursor, this.streamClosed);
 					const text = await response.text();
 					await subscriber({
 						text,
 						offset,
 						cursor,
-						upToDate
+						upToDate,
+						streamClosed
 					});
 					result = await reader.read();
 				}
@@ -1300,6 +1517,97 @@ var StreamResponseImpl = class {
 		return this.#closed;
 	}
 };
+/**
+* Extract stream metadata from Response headers.
+* Falls back to the provided defaults when headers are absent.
+*/
+function getMetadataFromResponse(response, fallbackOffset, fallbackCursor, fallbackStreamClosed) {
+	const offset = response.headers.get(STREAM_OFFSET_HEADER);
+	const cursor = response.headers.get(STREAM_CURSOR_HEADER);
+	const upToDate = response.headers.has(STREAM_UP_TO_DATE_HEADER);
+	const streamClosed = response.headers.get(STREAM_CLOSED_HEADER)?.toLowerCase() === `true`;
+	return {
+		offset: offset ?? fallbackOffset,
+		cursor: cursor ?? fallbackCursor,
+		upToDate,
+		streamClosed: streamClosed || fallbackStreamClosed
+	};
+}
+/**
+* Decode base64 string to Uint8Array.
+* Per protocol: concatenate data lines, remove \n and \r, then decode.
+*/
+function decodeBase64(base64Str) {
+	const cleaned = base64Str.replace(/[\n\r]/g, ``);
+	if (cleaned.length === 0) return new Uint8Array(0);
+	if (cleaned.length % 4 !== 0) throw new DurableStreamError(`Invalid base64 data: length ${cleaned.length} is not a multiple of 4`, `PARSE_ERROR`);
+	try {
+		if (typeof Buffer !== `undefined`) return new Uint8Array(Buffer.from(cleaned, `base64`));
+		else {
+			const binaryStr = atob(cleaned);
+			const bytes = new Uint8Array(binaryStr.length);
+			for (let i = 0; i < binaryStr.length; i++) bytes[i] = binaryStr.charCodeAt(i);
+			return bytes;
+		}
+	} catch (err) {
+		throw new DurableStreamError(`Failed to decode base64 data: ${err instanceof Error ? err.message : String(err)}`, `PARSE_ERROR`);
+	}
+}
+/**
+* Create a synthetic Response from SSE data with proper headers.
+* Includes offset/cursor/upToDate/streamClosed in headers so subscribers can read them.
+*/
+function createSSESyntheticResponse(data, offset, cursor, upToDate, streamClosed, contentType, encoding) {
+	return createSSESyntheticResponseFromParts([data], offset, cursor, upToDate, streamClosed, contentType, encoding);
+}
+/**
+* Create a synthetic Response from multiple SSE data parts.
+* For base64 mode, each part is independently encoded, so we decode each
+* separately and concatenate the binary results.
+* For text mode, parts are simply concatenated as strings.
+*/
+function createSSESyntheticResponseFromParts(dataParts, offset, cursor, upToDate, streamClosed, contentType, encoding, isJsonMode) {
+	const headers = {
+		"content-type": contentType ?? `application/json`,
+		[STREAM_OFFSET_HEADER]: String(offset)
+	};
+	if (cursor) headers[STREAM_CURSOR_HEADER] = cursor;
+	if (upToDate) headers[STREAM_UP_TO_DATE_HEADER] = `true`;
+	if (streamClosed) headers[STREAM_CLOSED_HEADER] = `true`;
+	let body;
+	if (encoding === `base64`) {
+		const decodedParts = dataParts.filter((part) => part.length > 0).map((part) => decodeBase64(part));
+		if (decodedParts.length === 0) body = new ArrayBuffer(0);
+		else if (decodedParts.length === 1) {
+			const decoded = decodedParts[0];
+			body = decoded.buffer.slice(decoded.byteOffset, decoded.byteOffset + decoded.byteLength);
+		} else {
+			const totalLength = decodedParts.reduce((sum, part) => sum + part.length, 0);
+			const combined = new Uint8Array(totalLength);
+			let offset$1 = 0;
+			for (const part of decodedParts) {
+				combined.set(part, offset$1);
+				offset$1 += part.length;
+			}
+			body = combined.buffer;
+		}
+	} else if (isJsonMode) {
+		const mergedParts = [];
+		for (const part of dataParts) {
+			const trimmed = part.trim();
+			if (trimmed.length === 0) continue;
+			if (trimmed.startsWith(`[`) && trimmed.endsWith(`]`)) {
+				const inner = trimmed.slice(1, -1).trim();
+				if (inner.length > 0) mergedParts.push(inner);
+			} else mergedParts.push(trimmed);
+		}
+		body = `[${mergedParts.join(`,`)}]`;
+	} else body = dataParts.join(``);
+	return new Response(body, {
+		status: 200,
+		headers
+	});
+}
 
 //#endregion
 //#region src/utils.ts
@@ -1322,6 +1630,11 @@ async function handleErrorResponse(response, url, context) {
 	const status = response.status;
 	if (status === 404) throw new DurableStreamError(`Stream not found: ${url}`, `NOT_FOUND`, 404);
 	if (status === 409) {
+		const streamClosedHeader = response.headers.get(STREAM_CLOSED_HEADER);
+		if (streamClosedHeader?.toLowerCase() === `true`) {
+			const finalOffset = response.headers.get(STREAM_OFFSET_HEADER) ?? void 0;
+			throw new StreamClosedError(url, finalOffset);
+		}
 		const message = context?.operation === `create` ? `Stream already exists: ${url}` : `Sequence conflict: seq is lower than last appended`;
 		const code = context?.operation === `create` ? `CONFLICT_EXISTS` : `CONFLICT_SEQ`;
 		throw new DurableStreamError(message, code, 409);
@@ -1508,7 +1821,10 @@ async function streamInternal(options) {
 	const initialOffset = firstResponse.headers.get(STREAM_OFFSET_HEADER) ?? startOffset;
 	const initialCursor = firstResponse.headers.get(STREAM_CURSOR_HEADER) ?? void 0;
 	const initialUpToDate = firstResponse.headers.has(STREAM_UP_TO_DATE_HEADER);
+	const initialStreamClosed = firstResponse.headers.get(STREAM_CLOSED_HEADER)?.toLowerCase() === `true`;
 	const isJsonMode = options.json === true || (contentType?.includes(`application/json`) ?? false);
+	const sseDataEncoding = firstResponse.headers.get(STREAM_SSE_DATA_ENCODING_HEADER);
+	const encoding = sseDataEncoding === `base64` ? `base64` : void 0;
 	const fetchNext = async (offset, cursor, signal, resumingFromPause) => {
 		const nextUrl = new URL(url);
 		nextUrl.searchParams.set(OFFSET_QUERY_PARAM, offset);
@@ -1553,11 +1869,13 @@ async function streamInternal(options) {
 		initialOffset,
 		initialCursor,
 		initialUpToDate,
+		initialStreamClosed,
 		firstResponse,
 		abortController,
 		fetchNext,
 		startSSE,
-		sseResilience: options.sseResilience
+		sseResilience: options.sseResilience,
+		encoding
 	});
 }
 
@@ -1648,6 +1966,8 @@ var IdempotentProducer = class {
 	#queue;
 	#maxInFlight;
 	#closed = false;
+	#closeResult = null;
+	#pendingFinalMessage;
 	#epochClaimed;
 	#seqState = new Map();
 	/**
@@ -1737,11 +2057,17 @@ var IdempotentProducer = class {
 		await this.#queue.drained();
 	}
 	/**
-	* Flush pending messages and close the producer.
+	* Stop the producer without closing the underlying stream.
 	*
-	* After calling close(), further append() calls will throw.
+	* 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
+	*
+	* Flushes any pending messages before detaching.
+	* After calling detach(), further append() calls will throw.
 	*/
-	async close() {
+	async detach() {
 		if (this.#closed) return;
 		this.#closed = true;
 		try {
@@ -1749,6 +2075,89 @@ var IdempotentProducer = class {
 		} catch {}
 	}
 	/**
+	* 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
+	*/
+	async close(finalMessage) {
+		if (this.#closed) {
+			if (this.#closeResult) return this.#closeResult;
+			await this.flush();
+			const result$1 = await this.#doClose(this.#pendingFinalMessage);
+			this.#closeResult = result$1;
+			return result$1;
+		}
+		this.#closed = true;
+		this.#pendingFinalMessage = finalMessage;
+		await this.flush();
+		const result = await this.#doClose(finalMessage);
+		this.#closeResult = result;
+		return result;
+	}
+	/**
+	* Actually close the stream with optional final message.
+	* Uses producer headers for idempotency.
+	*/
+	async #doClose(finalMessage) {
+		const contentType = this.#stream.contentType ?? `application/octet-stream`;
+		const isJson = normalizeContentType$1(contentType) === `application/json`;
+		let body;
+		if (finalMessage !== void 0) {
+			const bodyBytes = typeof finalMessage === `string` ? new TextEncoder().encode(finalMessage) : finalMessage;
+			if (isJson) {
+				const jsonStr = new TextDecoder().decode(bodyBytes);
+				body = `[${jsonStr}]`;
+			} else body = bodyBytes;
+		}
+		const seqForThisRequest = this.#nextSeq;
+		const headers = {
+			"content-type": contentType,
+			[PRODUCER_ID_HEADER]: this.#producerId,
+			[PRODUCER_EPOCH_HEADER]: this.#epoch.toString(),
+			[PRODUCER_SEQ_HEADER]: seqForThisRequest.toString(),
+			[STREAM_CLOSED_HEADER]: `true`
+		};
+		const response = await this.#fetchClient(this.#stream.url, {
+			method: `POST`,
+			headers,
+			body,
+			signal: this.#signal
+		});
+		if (response.status === 204) {
+			this.#nextSeq = seqForThisRequest + 1;
+			const finalOffset = response.headers.get(STREAM_OFFSET_HEADER) ?? ``;
+			return { finalOffset };
+		}
+		if (response.status === 200) {
+			this.#nextSeq = seqForThisRequest + 1;
+			const finalOffset = response.headers.get(STREAM_OFFSET_HEADER) ?? ``;
+			return { finalOffset };
+		}
+		if (response.status === 403) {
+			const currentEpochStr = response.headers.get(PRODUCER_EPOCH_HEADER);
+			const currentEpoch = currentEpochStr ? parseInt(currentEpochStr, 10) : this.#epoch;
+			if (this.#autoClaim) {
+				const newEpoch = currentEpoch + 1;
+				this.#epoch = newEpoch;
+				this.#nextSeq = 0;
+				return this.#doClose(finalMessage);
+			}
+			throw new StaleEpochError(currentEpoch);
+		}
+		const error = await FetchError.fromResponse(response, this.#stream.url);
+		throw error;
+	}
+	/**
 	* Increment epoch and reset sequence.
 	*
 	* Call this when restarting the producer to establish a new session.
@@ -2054,7 +2463,8 @@ var DurableStream = class DurableStream {
 			contentType: opts.contentType,
 			ttlSeconds: opts.ttlSeconds,
 			expiresAt: opts.expiresAt,
-			body: opts.body
+			body: opts.body,
+			closed: opts.closed
 		});
 		return stream$1;
 	}
@@ -2107,13 +2517,15 @@ var DurableStream = class DurableStream {
 		const offset = response.headers.get(STREAM_OFFSET_HEADER) ?? void 0;
 		const etag = response.headers.get(`etag`) ?? void 0;
 		const cacheControl = response.headers.get(`cache-control`) ?? void 0;
+		const streamClosed = response.headers.get(STREAM_CLOSED_HEADER)?.toLowerCase() === `true`;
 		if (contentType) this.contentType = contentType;
 		return {
 			exists: true,
 			contentType,
 			offset,
 			etag,
-			cacheControl
+			cacheControl,
+			streamClosed
 		};
 	}
 	/**
@@ -2125,6 +2537,7 @@ var DurableStream = class DurableStream {
 		if (contentType) requestHeaders[`content-type`] = contentType;
 		if (opts?.ttlSeconds !== void 0) requestHeaders[STREAM_TTL_HEADER] = String(opts.ttlSeconds);
 		if (opts?.expiresAt) requestHeaders[STREAM_EXPIRES_AT_HEADER] = opts.expiresAt;
+		if (opts?.closed) requestHeaders[STREAM_CLOSED_HEADER] = `true`;
 		const body = encodeBody(opts?.body);
 		const response = await this.#fetchClient(fetchUrl.toString(), {
 			method: `PUT`,
@@ -2151,6 +2564,57 @@ var DurableStream = class DurableStream {
 		if (!response.ok) await handleErrorResponse(response, this.url);
 	}
 	/**
+	* 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
+	*/
+	async close(opts) {
+		const { requestHeaders, fetchUrl } = await this.#buildRequest();
+		const contentType = opts?.contentType ?? this.#options.contentType ?? this.contentType;
+		if (contentType) requestHeaders[`content-type`] = contentType;
+		requestHeaders[STREAM_CLOSED_HEADER] = `true`;
+		let body;
+		if (opts?.body !== void 0) {
+			const isJson = normalizeContentType(contentType) === `application/json`;
+			if (isJson) {
+				const bodyStr = typeof opts.body === `string` ? opts.body : new TextDecoder().decode(opts.body);
+				body = `[${bodyStr}]`;
+			} else body = typeof opts.body === `string` ? opts.body : opts.body;
+		}
+		const response = await this.#fetchClient(fetchUrl.toString(), {
+			method: `POST`,
+			headers: requestHeaders,
+			body,
+			signal: opts?.signal ?? this.#options.signal
+		});
+		if (response.status === 409) {
+			const isClosed = response.headers.get(STREAM_CLOSED_HEADER)?.toLowerCase() === `true`;
+			if (isClosed) {
+				const finalOffset$1 = response.headers.get(STREAM_OFFSET_HEADER) ?? void 0;
+				throw new StreamClosedError(this.url, finalOffset$1);
+			}
+		}
+		if (!response.ok) await handleErrorResponse(response, this.url);
+		const finalOffset = response.headers.get(STREAM_OFFSET_HEADER) ?? ``;
+		return { finalOffset };
+	}
+	/**
 	* Append a single payload to the stream.
 	*
 	* When batching is enabled (default), multiple append() calls made while
@@ -2190,8 +2654,12 @@ var DurableStream = class DurableStream {
 		if (contentType) requestHeaders[`content-type`] = contentType;
 		if (opts?.seq) requestHeaders[STREAM_SEQ_HEADER] = opts.seq;
 		const isJson = normalizeContentType(contentType) === `application/json`;
-		const bodyStr = typeof body === `string` ? body : new TextDecoder().decode(body);
-		const encodedBody = isJson ? `[${bodyStr}]` : bodyStr;
+		let encodedBody;
+		if (isJson) {
+			const bodyStr = typeof body === `string` ? body : new TextDecoder().decode(body);
+			encodedBody = `[${bodyStr}]`;
+		} else if (typeof body === `string`) encodedBody = body;
+		else encodedBody = body.buffer.slice(body.byteOffset, body.byteOffset + body.byteLength);
 		const response = await this.#fetchClient(fetchUrl.toString(), {
 			method: `POST`,
 			headers: requestHeaders,
@@ -2261,8 +2729,31 @@ var DurableStream = class DurableStream {
 			const jsonStrings = batch.map((m) => typeof m.data === `string` ? m.data : new TextDecoder().decode(m.data));
 			batchedBody = `[${jsonStrings.join(`,`)}]`;
 		} else {
-			const strings = batch.map((m) => typeof m.data === `string` ? m.data : new TextDecoder().decode(m.data));
-			batchedBody = strings.join(``);
+			const hasUint8Array = batch.some((m) => m.data instanceof Uint8Array);
+			const hasString = batch.some((m) => typeof m.data === `string`);
+			if (hasUint8Array && !hasString) {
+				const chunks = batch.map((m) => m.data);
+				const totalLength = chunks.reduce((sum, c) => sum + c.length, 0);
+				const combined = new Uint8Array(totalLength);
+				let offset = 0;
+				for (const chunk of chunks) {
+					combined.set(chunk, offset);
+					offset += chunk.length;
+				}
+				batchedBody = combined;
+			} else if (hasString && !hasUint8Array) batchedBody = batch.map((m) => m.data).join(``);
+			else {
+				const encoder = new TextEncoder();
+				const chunks = batch.map((m) => typeof m.data === `string` ? encoder.encode(m.data) : m.data);
+				const totalLength = chunks.reduce((sum, c) => sum + c.length, 0);
+				const combined = new Uint8Array(totalLength);
+				let offset = 0;
+				for (const chunk of chunks) {
+					combined.set(chunk, offset);
+					offset += chunk.length;
+				}
+				batchedBody = combined;
+			}
 		}
 		const signals = [];
 		if (this.#options.signal) signals.push(this.#options.signal);
@@ -2370,12 +2861,11 @@ var DurableStream = class DurableStream {
 				producer.append(chunk);
 			},
 			async close() {
-				await producer.flush();
 				await producer.close();
 				if (writeError) throw writeError;
 			},
 			abort(_reason) {
-				producer.close().catch((err) => {
+				producer.detach().catch((err) => {
 					opts?.onError?.(err);
 				});
 			}
@@ -2417,10 +2907,6 @@ var DurableStream = class DurableStream {
 	* ```
 	*/
 	async stream(options) {
-		if (options?.live === `sse` && this.contentType) {
-			const isSSECompatible = SSE_COMPATIBLE_CONTENT_TYPES.some((prefix) => this.contentType.startsWith(prefix));
-			if (!isSSECompatible) throw new DurableStreamError(`SSE is not supported for content-type: ${this.contentType}`, `SSE_NOT_SUPPORTED`, 400);
-		}
 		const mergedHeaders = {
 			...this.#options.headers,
 			...options?.headers
@@ -2522,7 +3008,9 @@ exports.PRODUCER_EXPECTED_SEQ_HEADER = PRODUCER_EXPECTED_SEQ_HEADER
 exports.PRODUCER_ID_HEADER = PRODUCER_ID_HEADER
 exports.PRODUCER_RECEIVED_SEQ_HEADER = PRODUCER_RECEIVED_SEQ_HEADER
 exports.PRODUCER_SEQ_HEADER = PRODUCER_SEQ_HEADER
+exports.SSE_CLOSED_FIELD = SSE_CLOSED_FIELD
 exports.SSE_COMPATIBLE_CONTENT_TYPES = SSE_COMPATIBLE_CONTENT_TYPES
+exports.STREAM_CLOSED_HEADER = STREAM_CLOSED_HEADER
 exports.STREAM_CURSOR_HEADER = STREAM_CURSOR_HEADER
 exports.STREAM_EXPIRES_AT_HEADER = STREAM_EXPIRES_AT_HEADER
 exports.STREAM_OFFSET_HEADER = STREAM_OFFSET_HEADER
@@ -2531,6 +3019,7 @@ exports.STREAM_TTL_HEADER = STREAM_TTL_HEADER
 exports.STREAM_UP_TO_DATE_HEADER = STREAM_UP_TO_DATE_HEADER
 exports.SequenceGapError = SequenceGapError
 exports.StaleEpochError = StaleEpochError
+exports.StreamClosedError = StreamClosedError
 exports._resetHttpWarningForTesting = _resetHttpWarningForTesting
 exports.asAsyncIterableReadableStream = asAsyncIterableReadableStream
 exports.createFetchWithBackoff = createFetchWithBackoff