@durable-streams/client 0.1.1 → 0.1.2

package/dist/index.cjs

@@ -0,0 +1,1875 @@
+"use strict";
+//#region rolldown:runtime
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+	if (from && typeof from === "object" || typeof from === "function") for (var keys = __getOwnPropNames(from), i = 0, n = keys.length, key; i < n; i++) {
+		key = keys[i];
+		if (!__hasOwnProp.call(to, key) && key !== except) __defProp(to, key, {
+			get: ((k) => from[k]).bind(null, key),
+			enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+		});
+	}
+	return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", {
+	value: mod,
+	enumerable: true
+}) : target, mod));
+
+//#endregion
+const fastq = __toESM(require("fastq"));
+
+//#region src/constants.ts
+/**
+* Durable Streams Protocol Constants
+*
+* Header and query parameter names following the Electric Durable Stream Protocol.
+*/
+/**
+* Response header containing the next offset to read from.
+* Offsets are opaque tokens - clients MUST NOT interpret the format.
+*/
+const STREAM_OFFSET_HEADER = `Stream-Next-Offset`;
+/**
+* Response header for cursor (used for CDN collapsing).
+* Echo this value in subsequent long-poll requests.
+*/
+const STREAM_CURSOR_HEADER = `Stream-Cursor`;
+/**
+* Presence header indicating response ends at current end of stream.
+* When present (any value), indicates up-to-date.
+*/
+const STREAM_UP_TO_DATE_HEADER = `Stream-Up-To-Date`;
+/**
+* Request header for writer coordination sequence.
+* Monotonic, lexicographic. If lower than last appended seq -> 409 Conflict.
+*/
+const STREAM_SEQ_HEADER = `Stream-Seq`;
+/**
+* Request header for stream TTL in seconds (on create).
+*/
+const STREAM_TTL_HEADER = `Stream-TTL`;
+/**
+* Request header for absolute stream expiry time (RFC3339, on create).
+*/
+const STREAM_EXPIRES_AT_HEADER = `Stream-Expires-At`;
+/**
+* Query parameter for starting offset.
+*/
+const OFFSET_QUERY_PARAM = `offset`;
+/**
+* Query parameter for live mode.
+* Values: "long-poll", "sse"
+*/
+const LIVE_QUERY_PARAM = `live`;
+/**
+* Query parameter for echoing cursor (CDN collapsing).
+*/
+const CURSOR_QUERY_PARAM = `cursor`;
+/**
+* Content types that support SSE mode.
+* SSE is only valid for text/* or application/json streams.
+*/
+const SSE_COMPATIBLE_CONTENT_TYPES = [`text/`, `application/json`];
+/**
+* Protocol query parameters that should not be set by users.
+*/
+const DURABLE_STREAM_PROTOCOL_QUERY_PARAMS = [
+	OFFSET_QUERY_PARAM,
+	LIVE_QUERY_PARAM,
+	CURSOR_QUERY_PARAM
+];
+
+//#endregion
+//#region src/error.ts
+/**
+* Error thrown for transport/network errors.
+* Following the @electric-sql/client FetchError pattern.
+*/
+var FetchError = class FetchError extends Error {
+	status;
+	text;
+	json;
+	headers;
+	constructor(status, text, json, headers, url, message) {
+		super(message || `HTTP Error ${status} at ${url}: ${text ?? JSON.stringify(json)}`);
+		this.url = url;
+		this.name = `FetchError`;
+		this.status = status;
+		this.text = text;
+		this.json = json;
+		this.headers = headers;
+	}
+	static async fromResponse(response, url) {
+		const status = response.status;
+		const headers = Object.fromEntries([...response.headers.entries()]);
+		let text = void 0;
+		let json = void 0;
+		const contentType = response.headers.get(`content-type`);
+		if (!response.bodyUsed) if (contentType && contentType.includes(`application/json`)) try {
+			json = await response.json();
+		} catch {
+			text = await response.text();
+		}
+		else text = await response.text();
+		return new FetchError(status, text, json, headers, url);
+	}
+};
+/**
+* Error thrown when a fetch operation is aborted during backoff.
+*/
+var FetchBackoffAbortError = class extends Error {
+	constructor() {
+		super(`Fetch with backoff aborted`);
+		this.name = `FetchBackoffAbortError`;
+	}
+};
+/**
+* Protocol-level error for Durable Streams operations.
+* Provides structured error handling with error codes.
+*/
+var DurableStreamError = class DurableStreamError extends Error {
+	/**
+	* HTTP status code, if applicable.
+	*/
+	status;
+	/**
+	* Structured error code for programmatic handling.
+	*/
+	code;
+	/**
+	* Additional error details (e.g., raw response body).
+	*/
+	details;
+	constructor(message, code, status, details) {
+		super(message);
+		this.name = `DurableStreamError`;
+		this.code = code;
+		this.status = status;
+		this.details = details;
+	}
+	/**
+	* Create a DurableStreamError from an HTTP response.
+	*/
+	static async fromResponse(response, url) {
+		const status = response.status;
+		let details;
+		const contentType = response.headers.get(`content-type`);
+		if (!response.bodyUsed) if (contentType && contentType.includes(`application/json`)) try {
+			details = await response.json();
+		} catch {
+			details = await response.text();
+		}
+		else details = await response.text();
+		const code = statusToCode(status);
+		const message = `Durable stream error at ${url}: ${response.statusText || status}`;
+		return new DurableStreamError(message, code, status, details);
+	}
+	/**
+	* Create a DurableStreamError from a FetchError.
+	*/
+	static fromFetchError(error) {
+		const code = statusToCode(error.status);
+		return new DurableStreamError(error.message, code, error.status, error.json ?? error.text);
+	}
+};
+/**
+* Map HTTP status codes to DurableStreamErrorCode.
+*/
+function statusToCode(status) {
+	switch (status) {
+		case 400: return `BAD_REQUEST`;
+		case 401: return `UNAUTHORIZED`;
+		case 403: return `FORBIDDEN`;
+		case 404: return `NOT_FOUND`;
+		case 409: return `CONFLICT_SEQ`;
+		case 429: return `RATE_LIMITED`;
+		case 503: return `BUSY`;
+		default: return `UNKNOWN`;
+	}
+}
+/**
+* Error thrown when stream URL is missing.
+*/
+var MissingStreamUrlError = class extends Error {
+	constructor() {
+		super(`Invalid stream options: missing required url parameter`);
+		this.name = `MissingStreamUrlError`;
+	}
+};
+/**
+* Error thrown when signal option is invalid.
+*/
+var InvalidSignalError = class extends Error {
+	constructor() {
+		super(`Invalid signal option. It must be an instance of AbortSignal.`);
+		this.name = `InvalidSignalError`;
+	}
+};
+
+//#endregion
+//#region src/fetch.ts
+/**
+* HTTP status codes that should be retried.
+*/
+const HTTP_RETRY_STATUS_CODES = [429, 503];
+/**
+* Default backoff options.
+*/
+const BackoffDefaults = {
+	initialDelay: 100,
+	maxDelay: 6e4,
+	multiplier: 1.3,
+	maxRetries: Infinity
+};
+/**
+* Parse Retry-After header value and return delay in milliseconds.
+* Supports both delta-seconds format and HTTP-date format.
+* Returns 0 if header is not present or invalid.
+*/
+function parseRetryAfterHeader(retryAfter) {
+	if (!retryAfter) return 0;
+	const retryAfterSec = Number(retryAfter);
+	if (Number.isFinite(retryAfterSec) && retryAfterSec > 0) return retryAfterSec * 1e3;
+	const retryDate = Date.parse(retryAfter);
+	if (!isNaN(retryDate)) {
+		const deltaMs = retryDate - Date.now();
+		return Math.max(0, Math.min(deltaMs, 36e5));
+	}
+	return 0;
+}
+/**
+* Creates a fetch client that retries failed requests with exponential backoff.
+*
+* @param fetchClient - The base fetch client to wrap
+* @param backoffOptions - Options for retry behavior
+* @returns A fetch function with automatic retry
+*/
+function createFetchWithBackoff(fetchClient, backoffOptions = BackoffDefaults) {
+	const { initialDelay, maxDelay, multiplier, debug = false, onFailedAttempt, maxRetries = Infinity } = backoffOptions;
+	return async (...args) => {
+		const url = args[0];
+		const options = args[1];
+		let delay = initialDelay;
+		let attempt = 0;
+		while (true) try {
+			const result = await fetchClient(...args);
+			if (result.ok) return result;
+			const err = await FetchError.fromResponse(result, url.toString());
+			throw err;
+		} catch (e) {
+			onFailedAttempt?.();
+			if (options?.signal?.aborted) throw new FetchBackoffAbortError();
+			else if (e instanceof FetchError && !HTTP_RETRY_STATUS_CODES.includes(e.status) && e.status >= 400 && e.status < 500) throw e;
+			else {
+				attempt++;
+				if (attempt > maxRetries) {
+					if (debug) console.log(`Max retries reached (${attempt}/${maxRetries}), giving up`);
+					throw e;
+				}
+				const serverMinimumMs = e instanceof FetchError ? parseRetryAfterHeader(e.headers[`retry-after`]) : 0;
+				const jitter = Math.random() * delay;
+				const clientBackoffMs = Math.min(jitter, maxDelay);
+				const waitMs = Math.max(serverMinimumMs, clientBackoffMs);
+				if (debug) {
+					const source = serverMinimumMs > 0 ? `server+client` : `client`;
+					console.log(`Retry attempt #${attempt} after ${waitMs}ms (${source}, serverMin=${serverMinimumMs}ms, clientBackoff=${clientBackoffMs}ms)`);
+				}
+				await new Promise((resolve) => setTimeout(resolve, waitMs));
+				delay = Math.min(delay * multiplier, maxDelay);
+			}
+		}
+	};
+}
+/**
+* Status codes where we shouldn't try to read the body.
+*/
+const NO_BODY_STATUS_CODES = [
+	201,
+	204,
+	205
+];
+/**
+* Creates a fetch client that ensures the response body is fully consumed.
+* This prevents issues with connection pooling when bodies aren't read.
+*
+* Uses arrayBuffer() instead of text() to preserve binary data integrity.
+*
+* @param fetchClient - The base fetch client to wrap
+* @returns A fetch function that consumes response bodies
+*/
+function createFetchWithConsumedBody(fetchClient) {
+	return async (...args) => {
+		const url = args[0];
+		const res = await fetchClient(...args);
+		try {
+			if (res.status < 200 || NO_BODY_STATUS_CODES.includes(res.status)) return res;
+			const buf = await res.arrayBuffer();
+			return new Response(buf, {
+				status: res.status,
+				statusText: res.statusText,
+				headers: res.headers
+			});
+		} catch (err) {
+			if (args[1]?.signal?.aborted) throw new FetchBackoffAbortError();
+			throw new FetchError(res.status, void 0, void 0, Object.fromEntries([...res.headers.entries()]), url.toString(), err instanceof Error ? err.message : typeof err === `string` ? err : `failed to read body`);
+		}
+	};
+}
+
+//#endregion
+//#region src/asyncIterableReadableStream.ts
+/**
+* Check if a value has Symbol.asyncIterator defined.
+*/
+function hasAsyncIterator(stream$1) {
+	return typeof Symbol !== `undefined` && typeof Symbol.asyncIterator === `symbol` && typeof stream$1[Symbol.asyncIterator] === `function`;
+}
+/**
+* Define [Symbol.asyncIterator] and .values() on a ReadableStream instance.
+*
+* Uses getReader().read() to implement spec-consistent iteration.
+* On completion or early exit (break/return/throw), releases lock and cancels as appropriate.
+*
+* **Iterator behavior notes:**
+* - `return(value?)` accepts an optional cancellation reason passed to `reader.cancel()`
+* - `return()` always resolves with `{ done: true, value: undefined }` regardless of the
+*   input value. This matches `for await...of` semantics where the return value is ignored.
+*   Manual iteration users should be aware of this behavior.
+*/
+function defineAsyncIterator(stream$1) {
+	if (typeof Symbol === `undefined` || typeof Symbol.asyncIterator !== `symbol`) return;
+	if (typeof stream$1[Symbol.asyncIterator] === `function`) return;
+	const createIterator = function() {
+		const reader = this.getReader();
+		let finished = false;
+		let pendingReads = 0;
+		const iterator = {
+			async next() {
+				if (finished) return {
+					done: true,
+					value: void 0
+				};
+				pendingReads++;
+				try {
+					const { value, done } = await reader.read();
+					if (done) {
+						finished = true;
+						reader.releaseLock();
+						return {
+							done: true,
+							value: void 0
+						};
+					}
+					return {
+						done: false,
+						value
+					};
+				} catch (err) {
+					finished = true;
+					try {
+						reader.releaseLock();
+					} catch {}
+					throw err;
+				} finally {
+					pendingReads--;
+				}
+			},
+			async return(value) {
+				if (pendingReads > 0) throw new TypeError(`Cannot close a readable stream reader when it has pending read requests`);
+				finished = true;
+				const cancelPromise = reader.cancel(value);
+				reader.releaseLock();
+				await cancelPromise;
+				return {
+					done: true,
+					value: void 0
+				};
+			},
+			async throw(err) {
+				if (pendingReads > 0) throw new TypeError(`Cannot close a readable stream reader when it has pending read requests`);
+				finished = true;
+				const cancelPromise = reader.cancel(err);
+				reader.releaseLock();
+				await cancelPromise;
+				throw err;
+			},
+			[Symbol.asyncIterator]() {
+				return this;
+			}
+		};
+		return iterator;
+	};
+	try {
+		Object.defineProperty(stream$1, Symbol.asyncIterator, {
+			configurable: true,
+			writable: true,
+			value: createIterator
+		});
+	} catch {
+		return;
+	}
+	try {
+		Object.defineProperty(stream$1, `values`, {
+			configurable: true,
+			writable: true,
+			value: createIterator
+		});
+	} catch {}
+}
+/**
+* Ensure a ReadableStream is async-iterable.
+*
+* If the stream already has [Symbol.asyncIterator] defined (native or polyfilled),
+* it is returned as-is. Otherwise, [Symbol.asyncIterator] is defined on the
+* stream instance (not the prototype).
+*
+* The returned value is the same ReadableStream instance, so:
+* - `stream instanceof ReadableStream` remains true
+* - Any code relying on native branding/internal slots continues to work
+*
+* @example
+* ```typescript
+* const stream = someApiReturningReadableStream();
+* const iterableStream = asAsyncIterableReadableStream(stream);
+*
+* // Now works on Safari/iOS:
+* for await (const chunk of iterableStream) {
+*   console.log(chunk);
+* }
+* ```
+*/
+function asAsyncIterableReadableStream(stream$1) {
+	if (!hasAsyncIterator(stream$1)) defineAsyncIterator(stream$1);
+	return stream$1;
+}
+
+//#endregion
+//#region src/sse.ts
+/**
+* Parse SSE events from a ReadableStream<Uint8Array>.
+* Yields parsed events as they arrive.
+*/
+async function* parseSSEStream(stream$1, signal) {
+	const reader = stream$1.getReader();
+	const decoder = new TextDecoder();
+	let buffer = ``;
+	let currentEvent = { data: [] };
+	try {
+		while (true) {
+			if (signal?.aborted) break;
+			const { done, value } = await reader.read();
+			if (done) break;
+			buffer += decoder.decode(value, { stream: true });
+			const lines = buffer.split(`\n`);
+			buffer = lines.pop() ?? ``;
+			for (const line of lines) if (line === ``) {
+				if (currentEvent.type && currentEvent.data.length > 0) {
+					const dataStr = currentEvent.data.join(`\n`);
+					if (currentEvent.type === `data`) yield {
+						type: `data`,
+						data: dataStr
+					};
+					else if (currentEvent.type === `control`) try {
+						const control = JSON.parse(dataStr);
+						yield {
+							type: `control`,
+							streamNextOffset: control.streamNextOffset,
+							streamCursor: control.streamCursor,
+							upToDate: control.upToDate
+						};
+					} catch {}
+				}
+				currentEvent = { data: [] };
+			} else if (line.startsWith(`event:`)) currentEvent.type = line.slice(6).trim();
+			else if (line.startsWith(`data:`)) {
+				const content = line.slice(5);
+				currentEvent.data.push(content.startsWith(` `) ? content.slice(1) : content);
+			}
+		}
+		const remaining = decoder.decode();
+		if (remaining) buffer += remaining;
+		if (buffer && currentEvent.type && currentEvent.data.length > 0) {
+			const dataStr = currentEvent.data.join(`\n`);
+			if (currentEvent.type === `data`) yield {
+				type: `data`,
+				data: dataStr
+			};
+			else if (currentEvent.type === `control`) try {
+				const control = JSON.parse(dataStr);
+				yield {
+					type: `control`,
+					streamNextOffset: control.streamNextOffset,
+					streamCursor: control.streamCursor,
+					upToDate: control.upToDate
+				};
+			} catch {}
+		}
+	} finally {
+		reader.releaseLock();
+	}
+}
+
+//#endregion
+//#region src/response.ts
+/**
+* Implementation of the StreamResponse interface.
+*/
+var StreamResponseImpl = class {
+	url;
+	contentType;
+	live;
+	startOffset;
+	#headers;
+	#status;
+	#statusText;
+	#ok;
+	#isLoading;
+	offset;
+	cursor;
+	upToDate;
+	#isJsonMode;
+	#abortController;
+	#fetchNext;
+	#startSSE;
+	#closedResolve;
+	#closedReject;
+	#closed;
+	#stopAfterUpToDate = false;
+	#consumptionMethod = null;
+	#sseResilience;
+	#lastSSEConnectionStartTime;
+	#consecutiveShortSSEConnections = 0;
+	#sseFallbackToLongPoll = false;
+	#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;
+		this.#headers = config.firstResponse.headers;
+		this.#status = config.firstResponse.status;
+		this.#statusText = config.firstResponse.statusText;
+		this.#ok = config.firstResponse.ok;
+		this.#isLoading = false;
+		this.#isJsonMode = config.isJsonMode;
+		this.#abortController = config.abortController;
+		this.#fetchNext = config.fetchNext;
+		this.#startSSE = config.startSSE;
+		this.#sseResilience = {
+			minConnectionDuration: config.sseResilience?.minConnectionDuration ?? 1e3,
+			maxShortConnections: config.sseResilience?.maxShortConnections ?? 3,
+			backoffBaseDelay: config.sseResilience?.backoffBaseDelay ?? 100,
+			backoffMaxDelay: config.sseResilience?.backoffMaxDelay ?? 5e3,
+			logWarnings: config.sseResilience?.logWarnings ?? true
+		};
+		this.#closed = new Promise((resolve, reject) => {
+			this.#closedResolve = resolve;
+			this.#closedReject = reject;
+		});
+		this.#responseStream = this.#createResponseStream(config.firstResponse);
+	}
+	get headers() {
+		return this.#headers;
+	}
+	get status() {
+		return this.#status;
+	}
+	get statusText() {
+		return this.#statusText;
+	}
+	get ok() {
+		return this.#ok;
+	}
+	get isLoading() {
+		return this.#isLoading;
+	}
+	#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`);
+	}
+	#markClosed() {
+		this.#closedResolve();
+	}
+	#markError(err) {
+		this.#closedReject(err);
+	}
+	/**
+	* Ensure only one consumption method is used per StreamResponse.
+	* Throws if any consumption method was already called.
+	*/
+	#ensureNoConsumption(method) {
+		if (this.#consumptionMethod !== null) throw new DurableStreamError(`Cannot call ${method}() - this StreamResponse is already being consumed via ${this.#consumptionMethod}()`, `ALREADY_CONSUMED`);
+		this.#consumptionMethod = method;
+	}
+	/**
+	* Determine if we should continue with live updates based on live mode
+	* and whether we've received upToDate.
+	*/
+	#shouldContinueLive() {
+		if (this.#stopAfterUpToDate && this.upToDate) return false;
+		if (this.live === false) return false;
+		return true;
+	}
+	/**
+	* 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.#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;
+	}
+	/**
+	* Mark the start of an SSE connection for duration tracking.
+	*/
+	#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;
+	}
+	/**
+	* 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.#shouldContinueLive() || !this.#startSSE) return null;
+		const delayOrNull = await this.#handleSSEConnectionEnd();
+		if (delayOrNull === null) return null;
+		this.#markSSEConnectionStart();
+		const newSSEResponse = await this.#startSSE(this.offset, this.cursor, this.#abortController.signal);
+		if (newSSEResponse.body) return parseSSEStream(newSSEResponse.body, this.#abortController.signal);
+		return null;
+	}
+	/**
+	* Process SSE events from the iterator.
+	* Returns an object indicating the result:
+	* - { type: 'response', response, newIterator? } - yield this response
+	* - { type: 'closed' } - stream should be closed
+	* - { type: 'error', error } - an error occurred
+	* - { type: 'continue', newIterator? } - continue processing (control-only event)
+	*/
+	async #processSSEEvents(sseEventIterator) {
+		const { done, value: event } = await sseEventIterator.next();
+		if (done) {
+			try {
+				const newIterator = await this.#trySSEReconnect();
+				if (newIterator) return {
+					type: `continue`,
+					newIterator
+				};
+			} catch (err) {
+				return {
+					type: `error`,
+					error: err instanceof Error ? err : new Error(`SSE reconnection failed`)
+				};
+			}
+			return { type: `closed` };
+		}
+		if (event.type === `data`) return this.#processSSEDataEvent(event.data, sseEventIterator);
+		this.#updateStateFromSSEControl(event);
+		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.
+	*/
+	async #processSSEDataEvent(pendingData, sseEventIterator) {
+		let bufferedData = pendingData;
+		while (true) {
+			const { done: controlDone, value: controlEvent } = await sseEventIterator.next();
+			if (controlDone) {
+				const response = this.#createSSESyntheticResponse(bufferedData, this.offset, this.cursor, this.upToDate);
+				try {
+					const newIterator = await this.#trySSEReconnect();
+					return {
+						type: `response`,
+						response,
+						newIterator: newIterator ?? void 0
+					};
+				} catch (err) {
+					return {
+						type: `error`,
+						error: err instanceof Error ? err : new Error(`SSE reconnection failed`)
+					};
+				}
+			}
+			if (controlEvent.type === `control`) {
+				this.#updateStateFromSSEControl(controlEvent);
+				const response = this.#createSSESyntheticResponse(bufferedData, controlEvent.streamNextOffset, controlEvent.streamCursor, controlEvent.upToDate ?? false);
+				return {
+					type: `response`,
+					response
+				};
+			}
+			bufferedData += controlEvent.data;
+		}
+	}
+	/**
+	* Create the core ReadableStream<Response> that yields responses.
+	* This is consumed once - all consumption methods use this same stream.
+	*
+	* For long-poll mode: yields actual Response objects.
+	* For SSE mode: yields synthetic Response objects created from SSE data events.
+	*/
+	#createResponseStream(firstResponse) {
+		let firstResponseYielded = false;
+		let sseEventIterator = null;
+		return new ReadableStream({
+			pull: async (controller) => {
+				try {
+					if (!firstResponseYielded) {
+						firstResponseYielded = true;
+						const isSSE = firstResponse.headers.get(`content-type`)?.includes(`text/event-stream`) ?? false;
+						if (isSSE && firstResponse.body) {
+							this.#markSSEConnectionStart();
+							sseEventIterator = parseSSEStream(firstResponse.body, this.#abortController.signal);
+						} else {
+							controller.enqueue(firstResponse);
+							if (this.upToDate && !this.#shouldContinueLive()) {
+								this.#markClosed();
+								controller.close();
+								return;
+							}
+							return;
+						}
+					}
+					if (sseEventIterator) while (true) {
+						const result = await this.#processSSEEvents(sseEventIterator);
+						switch (result.type) {
+							case `response`:
+								if (result.newIterator) sseEventIterator = result.newIterator;
+								controller.enqueue(result.response);
+								return;
+							case `closed`:
+								this.#markClosed();
+								controller.close();
+								return;
+							case `error`:
+								this.#markError(result.error);
+								controller.error(result.error);
+								return;
+							case `continue`:
+								if (result.newIterator) sseEventIterator = result.newIterator;
+								continue;
+						}
+					}
+					if (this.#shouldContinueLive()) {
+						if (this.#abortController.signal.aborted) {
+							this.#markClosed();
+							controller.close();
+							return;
+						}
+						const response = await this.#fetchNext(this.offset, this.cursor, this.#abortController.signal);
+						this.#updateStateFromResponse(response);
+						controller.enqueue(response);
+						return;
+					}
+					this.#markClosed();
+					controller.close();
+				} catch (err) {
+					if (this.#abortController.signal.aborted) {
+						this.#markClosed();
+						controller.close();
+					} else {
+						this.#markError(err instanceof Error ? err : new Error(String(err)));
+						controller.error(err);
+					}
+				}
+			},
+			cancel: () => {
+				this.#abortController.abort();
+				this.#markClosed();
+			}
+		});
+	}
+	/**
+	* Get the response stream reader. Can only be called once.
+	*/
+	#getResponseReader() {
+		return this.#responseStream.getReader();
+	}
+	async body() {
+		this.#ensureNoConsumption(`body`);
+		this.#stopAfterUpToDate = true;
+		const reader = this.#getResponseReader();
+		const blobs = [];
+		try {
+			let result = await reader.read();
+			while (!result.done) {
+				const wasUpToDate = this.upToDate;
+				const blob = await result.value.blob();
+				if (blob.size > 0) blobs.push(blob);
+				if (wasUpToDate) break;
+				result = await reader.read();
+			}
+		} finally {
+			reader.releaseLock();
+		}
+		this.#markClosed();
+		if (blobs.length === 0) return new Uint8Array(0);
+		if (blobs.length === 1) return new Uint8Array(await blobs[0].arrayBuffer());
+		const combined = new Blob(blobs);
+		return new Uint8Array(await combined.arrayBuffer());
+	}
+	async json() {
+		this.#ensureNoConsumption(`json`);
+		this.#ensureJsonMode();
+		this.#stopAfterUpToDate = true;
+		const reader = this.#getResponseReader();
+		const items = [];
+		try {
+			let result = await reader.read();
+			while (!result.done) {
+				const wasUpToDate = this.upToDate;
+				const text = await result.value.text();
+				const content = text.trim() || `[]`;
+				const parsed = JSON.parse(content);
+				if (Array.isArray(parsed)) items.push(...parsed);
+				else items.push(parsed);
+				if (wasUpToDate) break;
+				result = await reader.read();
+			}
+		} finally {
+			reader.releaseLock();
+		}
+		this.#markClosed();
+		return items;
+	}
+	async text() {
+		this.#ensureNoConsumption(`text`);
+		this.#stopAfterUpToDate = true;
+		const reader = this.#getResponseReader();
+		const parts = [];
+		try {
+			let result = await reader.read();
+			while (!result.done) {
+				const wasUpToDate = this.upToDate;
+				const text = await result.value.text();
+				if (text) parts.push(text);
+				if (wasUpToDate) break;
+				result = await reader.read();
+			}
+		} finally {
+			reader.releaseLock();
+		}
+		this.#markClosed();
+		return parts.join(``);
+	}
+	/**
+	* Internal helper to create the body stream without consumption check.
+	* Used by both bodyStream() and textStream().
+	*/
+	#createBodyStreamInternal() {
+		const { readable, writable } = new TransformStream();
+		const reader = this.#getResponseReader();
+		const pipeBodyStream = async () => {
+			try {
+				let result = await reader.read();
+				while (!result.done) {
+					const wasUpToDate = this.upToDate;
+					const body = result.value.body;
+					if (body) await body.pipeTo(writable, {
+						preventClose: true,
+						preventAbort: true,
+						preventCancel: true
+					});
+					if (wasUpToDate && !this.#shouldContinueLive()) break;
+					result = await reader.read();
+				}
+				await writable.close();
+				this.#markClosed();
+			} catch (err) {
+				if (this.#abortController.signal.aborted) {
+					try {
+						await writable.close();
+					} catch {}
+					this.#markClosed();
+				} else {
+					try {
+						await writable.abort(err);
+					} catch {}
+					this.#markError(err instanceof Error ? err : new Error(String(err)));
+				}
+			} finally {
+				reader.releaseLock();
+			}
+		};
+		pipeBodyStream();
+		return readable;
+	}
+	bodyStream() {
+		this.#ensureNoConsumption(`bodyStream`);
+		return asAsyncIterableReadableStream(this.#createBodyStreamInternal());
+	}
+	jsonStream() {
+		this.#ensureNoConsumption(`jsonStream`);
+		this.#ensureJsonMode();
+		const reader = this.#getResponseReader();
+		let pendingItems = [];
+		const stream$1 = new ReadableStream({
+			pull: async (controller) => {
+				if (pendingItems.length > 0) {
+					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() || `[]`;
+				const parsed = JSON.parse(content);
+				pendingItems = Array.isArray(parsed) ? parsed : [parsed];
+				if (pendingItems.length > 0) controller.enqueue(pendingItems.shift());
+			},
+			cancel: () => {
+				reader.releaseLock();
+				this.cancel();
+			}
+		});
+		return asAsyncIterableReadableStream(stream$1);
+	}
+	textStream() {
+		this.#ensureNoConsumption(`textStream`);
+		const decoder = new TextDecoder();
+		const stream$1 = this.#createBodyStreamInternal().pipeThrough(new TransformStream({
+			transform(chunk, controller) {
+				controller.enqueue(decoder.decode(chunk, { stream: true }));
+			},
+			flush(controller) {
+				const remaining = decoder.decode();
+				if (remaining) controller.enqueue(remaining);
+			}
+		}));
+		return asAsyncIterableReadableStream(stream$1);
+	}
+	subscribeJson(subscriber) {
+		this.#ensureNoConsumption(`subscribeJson`);
+		this.#ensureJsonMode();
+		const abortController = new AbortController();
+		const reader = this.#getResponseReader();
+		const consumeJsonSubscription = async () => {
+			try {
+				let result = await reader.read();
+				while (!result.done) {
+					if (abortController.signal.aborted) break;
+					const response = result.value;
+					const { offset, cursor, upToDate } = this.#getMetadataFromResponse(response);
+					const text = await response.text();
+					const content = text.trim() || `[]`;
+					const parsed = JSON.parse(content);
+					const items = Array.isArray(parsed) ? parsed : [parsed];
+					await subscriber({
+						items,
+						offset,
+						cursor,
+						upToDate
+					});
+					result = await reader.read();
+				}
+				this.#markClosed();
+			} catch (e) {
+				const isAborted = abortController.signal.aborted;
+				const isBodyError = e instanceof TypeError && String(e).includes(`Body`);
+				if (!isAborted && !isBodyError) this.#markError(e instanceof Error ? e : new Error(String(e)));
+				else this.#markClosed();
+			} finally {
+				reader.releaseLock();
+			}
+		};
+		consumeJsonSubscription();
+		return () => {
+			abortController.abort();
+			this.cancel();
+		};
+	}
+	subscribeBytes(subscriber) {
+		this.#ensureNoConsumption(`subscribeBytes`);
+		const abortController = new AbortController();
+		const reader = this.#getResponseReader();
+		const consumeBytesSubscription = async () => {
+			try {
+				let result = await reader.read();
+				while (!result.done) {
+					if (abortController.signal.aborted) break;
+					const response = result.value;
+					const { offset, cursor, upToDate } = this.#getMetadataFromResponse(response);
+					const buffer = await response.arrayBuffer();
+					await subscriber({
+						data: new Uint8Array(buffer),
+						offset,
+						cursor,
+						upToDate
+					});
+					result = await reader.read();
+				}
+				this.#markClosed();
+			} catch (e) {
+				const isAborted = abortController.signal.aborted;
+				const isBodyError = e instanceof TypeError && String(e).includes(`Body`);
+				if (!isAborted && !isBodyError) this.#markError(e instanceof Error ? e : new Error(String(e)));
+				else this.#markClosed();
+			} finally {
+				reader.releaseLock();
+			}
+		};
+		consumeBytesSubscription();
+		return () => {
+			abortController.abort();
+			this.cancel();
+		};
+	}
+	subscribeText(subscriber) {
+		this.#ensureNoConsumption(`subscribeText`);
+		const abortController = new AbortController();
+		const reader = this.#getResponseReader();
+		const consumeTextSubscription = async () => {
+			try {
+				let result = await reader.read();
+				while (!result.done) {
+					if (abortController.signal.aborted) break;
+					const response = result.value;
+					const { offset, cursor, upToDate } = this.#getMetadataFromResponse(response);
+					const text = await response.text();
+					await subscriber({
+						text,
+						offset,
+						cursor,
+						upToDate
+					});
+					result = await reader.read();
+				}
+				this.#markClosed();
+			} catch (e) {
+				const isAborted = abortController.signal.aborted;
+				const isBodyError = e instanceof TypeError && String(e).includes(`Body`);
+				if (!isAborted && !isBodyError) this.#markError(e instanceof Error ? e : new Error(String(e)));
+				else this.#markClosed();
+			} finally {
+				reader.releaseLock();
+			}
+		};
+		consumeTextSubscription();
+		return () => {
+			abortController.abort();
+			this.cancel();
+		};
+	}
+	cancel(reason) {
+		this.#abortController.abort(reason);
+		this.#markClosed();
+	}
+	get closed() {
+		return this.#closed;
+	}
+};
+
+//#endregion
+//#region src/utils.ts
+/**
+* Resolve headers from HeadersRecord (supports async functions).
+* Unified implementation used by both stream() and DurableStream.
+*/
+async function resolveHeaders(headers) {
+	const resolved = {};
+	if (!headers) return resolved;
+	for (const [key, value] of Object.entries(headers)) if (typeof value === `function`) resolved[key] = await value();
+	else resolved[key] = value;
+	return resolved;
+}
+/**
+* Handle error responses from the server.
+* Throws appropriate DurableStreamError based on status code.
+*/
+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 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);
+	}
+	if (status === 400) throw new DurableStreamError(`Bad request (possibly content-type mismatch)`, `BAD_REQUEST`, 400);
+	throw await DurableStreamError.fromResponse(response, url);
+}
+/**
+* Resolve params from ParamsRecord (supports async functions).
+*/
+async function resolveParams(params) {
+	const resolved = {};
+	if (!params) return resolved;
+	for (const [key, value] of Object.entries(params)) if (value !== void 0) if (typeof value === `function`) resolved[key] = await value();
+	else resolved[key] = value;
+	return resolved;
+}
+
+//#endregion
+//#region src/stream-api.ts
+/**
+* Create a streaming session to read from a durable stream.
+*
+* This is a fetch-like API:
+* - The promise resolves after the first network request succeeds
+* - It rejects for auth/404/other protocol errors
+* - Returns a StreamResponse for consuming the data
+*
+* @example
+* ```typescript
+* // Catch-up JSON:
+* const res = await stream<{ message: string }>({
+*   url,
+*   auth,
+*   offset: "0",
+*   live: false,
+* })
+* const items = await res.json()
+*
+* // Live JSON:
+* const live = await stream<{ message: string }>({
+*   url,
+*   auth,
+*   offset: savedOffset,
+*   live: "auto",
+* })
+* live.subscribeJson(async (batch) => {
+*   for (const item of batch.items) {
+*     handle(item)
+*   }
+* })
+* ```
+*/
+async function stream(options) {
+	if (!options.url) throw new DurableStreamError(`Invalid stream options: missing required url parameter`, `BAD_REQUEST`);
+	let currentHeaders = options.headers;
+	let currentParams = options.params;
+	while (true) try {
+		return await streamInternal({
+			...options,
+			headers: currentHeaders,
+			params: currentParams
+		});
+	} catch (err) {
+		if (options.onError) {
+			const retryOpts = await options.onError(err instanceof Error ? err : new Error(String(err)));
+			if (retryOpts === void 0) throw err;
+			if (retryOpts.params) currentParams = {
+				...currentParams,
+				...retryOpts.params
+			};
+			if (retryOpts.headers) currentHeaders = {
+				...currentHeaders,
+				...retryOpts.headers
+			};
+			continue;
+		}
+		throw err;
+	}
+}
+/**
+* Internal implementation of stream that doesn't handle onError retries.
+*/
+async function streamInternal(options) {
+	const url = options.url instanceof URL ? options.url.toString() : options.url;
+	const fetchUrl = new URL(url);
+	const startOffset = options.offset ?? `-1`;
+	fetchUrl.searchParams.set(OFFSET_QUERY_PARAM, startOffset);
+	const live = options.live ?? `auto`;
+	if (live === `long-poll` || live === `sse`) fetchUrl.searchParams.set(LIVE_QUERY_PARAM, live);
+	const params = await resolveParams(options.params);
+	for (const [key, value] of Object.entries(params)) fetchUrl.searchParams.set(key, value);
+	const headers = await resolveHeaders(options.headers);
+	const abortController = new AbortController();
+	if (options.signal) options.signal.addEventListener(`abort`, () => abortController.abort(options.signal?.reason), { once: true });
+	const baseFetchClient = options.fetch ?? ((...args) => fetch(...args));
+	const backoffOptions = options.backoffOptions ?? BackoffDefaults;
+	const fetchClient = createFetchWithBackoff(baseFetchClient, backoffOptions);
+	let firstResponse;
+	try {
+		firstResponse = await fetchClient(fetchUrl.toString(), {
+			method: `GET`,
+			headers,
+			signal: abortController.signal
+		});
+	} catch (err) {
+		if (err instanceof FetchBackoffAbortError) throw new DurableStreamError(`Stream request was aborted`, `UNKNOWN`);
+		throw err;
+	}
+	const contentType = firstResponse.headers.get(`content-type`) ?? void 0;
+	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 isJsonMode = options.json === true || (contentType?.includes(`application/json`) ?? false);
+	const fetchNext = async (offset, cursor, signal) => {
+		const nextUrl = new URL(url);
+		nextUrl.searchParams.set(OFFSET_QUERY_PARAM, offset);
+		if (live === `auto` || live === `long-poll`) nextUrl.searchParams.set(LIVE_QUERY_PARAM, `long-poll`);
+		else if (live === `sse`) nextUrl.searchParams.set(LIVE_QUERY_PARAM, `sse`);
+		if (cursor) nextUrl.searchParams.set(`cursor`, cursor);
+		const nextParams = await resolveParams(options.params);
+		for (const [key, value] of Object.entries(nextParams)) nextUrl.searchParams.set(key, value);
+		const nextHeaders = await resolveHeaders(options.headers);
+		const response = await fetchClient(nextUrl.toString(), {
+			method: `GET`,
+			headers: nextHeaders,
+			signal
+		});
+		if (!response.ok) await handleErrorResponse(response, url);
+		return response;
+	};
+	const startSSE = live === `sse` ? async (offset, cursor, signal) => {
+		const sseUrl = new URL(url);
+		sseUrl.searchParams.set(OFFSET_QUERY_PARAM, offset);
+		sseUrl.searchParams.set(LIVE_QUERY_PARAM, `sse`);
+		if (cursor) sseUrl.searchParams.set(`cursor`, cursor);
+		const sseParams = await resolveParams(options.params);
+		for (const [key, value] of Object.entries(sseParams)) sseUrl.searchParams.set(key, value);
+		const sseHeaders = await resolveHeaders(options.headers);
+		const response = await fetchClient(sseUrl.toString(), {
+			method: `GET`,
+			headers: sseHeaders,
+			signal
+		});
+		if (!response.ok) await handleErrorResponse(response, url);
+		return response;
+	} : void 0;
+	return new StreamResponseImpl({
+		url,
+		contentType,
+		live,
+		startOffset,
+		isJsonMode,
+		initialOffset,
+		initialCursor,
+		initialUpToDate,
+		firstResponse,
+		abortController,
+		fetchNext,
+		startSSE,
+		sseResilience: options.sseResilience
+	});
+}
+
+//#endregion
+//#region src/stream.ts
+/**
+* Normalize content-type by extracting the media type (before any semicolon).
+* Handles cases like "application/json; charset=utf-8".
+*/
+function normalizeContentType(contentType) {
+	if (!contentType) return ``;
+	return contentType.split(`;`)[0].trim().toLowerCase();
+}
+/**
+* Check if a value is a Promise or Promise-like (thenable).
+*/
+function isPromiseLike(value) {
+	return value !== null && typeof value === `object` && `then` in value && typeof value.then === `function`;
+}
+/**
+* A handle to a remote durable stream for read/write operations.
+*
+* This is a lightweight, reusable handle - not a persistent connection.
+* It does not automatically start reading or listening.
+* Create sessions as needed via stream().
+*
+* @example
+* ```typescript
+* // Create a new stream
+* const stream = await DurableStream.create({
+*   url: "https://streams.example.com/my-stream",
+*   headers: { Authorization: "Bearer my-token" },
+*   contentType: "application/json"
+* });
+*
+* // Write data
+* await stream.append({ message: "hello" });
+*
+* // Read with the new API
+* const res = await stream.stream<{ message: string }>();
+* res.subscribeJson(async (batch) => {
+*   for (const item of batch.items) {
+*     console.log(item.message);
+*   }
+* });
+* ```
+*/
+var DurableStream = class DurableStream {
+	/**
+	* The URL of the durable stream.
+	*/
+	url;
+	/**
+	* The content type of the stream (populated after connect/head/read).
+	*/
+	contentType;
+	#options;
+	#fetchClient;
+	#onError;
+	#batchingEnabled;
+	#queue;
+	#buffer = [];
+	/**
+	* Create a cold handle to a stream.
+	* No network IO is performed by the constructor.
+	*/
+	constructor(opts) {
+		validateOptions(opts);
+		const urlStr = opts.url instanceof URL ? opts.url.toString() : opts.url;
+		this.url = urlStr;
+		this.#options = {
+			...opts,
+			url: urlStr
+		};
+		this.#onError = opts.onError;
+		this.#batchingEnabled = opts.batching !== false;
+		if (this.#batchingEnabled) this.#queue = fastq.default.promise(this.#batchWorker.bind(this), 1);
+		const baseFetchClient = opts.fetch ?? ((...args) => fetch(...args));
+		const backOffOpts = { ...opts.backoffOptions ?? BackoffDefaults };
+		const fetchWithBackoffClient = createFetchWithBackoff(baseFetchClient, backOffOpts);
+		this.#fetchClient = createFetchWithConsumedBody(fetchWithBackoffClient);
+	}
+	/**
+	* Create a new stream (create-only PUT) and return a handle.
+	* Fails with DurableStreamError(code="CONFLICT_EXISTS") if it already exists.
+	*/
+	static async create(opts) {
+		const stream$1 = new DurableStream(opts);
+		await stream$1.create({
+			contentType: opts.contentType,
+			ttlSeconds: opts.ttlSeconds,
+			expiresAt: opts.expiresAt,
+			body: opts.body
+		});
+		return stream$1;
+	}
+	/**
+	* Validate that a stream exists and fetch metadata via HEAD.
+	* Returns a handle with contentType populated (if sent by server).
+	*
+	* **Important**: This only performs a HEAD request for validation - it does
+	* NOT open a session or start reading data. To read from the stream, call
+	* `stream()` on the returned handle.
+	*
+	* @example
+	* ```typescript
+	* // Validate stream exists before reading
+	* const handle = await DurableStream.connect({ url })
+	* const res = await handle.stream() // Now actually read
+	* ```
+	*/
+	static async connect(opts) {
+		const stream$1 = new DurableStream(opts);
+		await stream$1.head();
+		return stream$1;
+	}
+	/**
+	* HEAD metadata for a stream without creating a handle.
+	*/
+	static async head(opts) {
+		const stream$1 = new DurableStream(opts);
+		return stream$1.head();
+	}
+	/**
+	* Delete a stream without creating a handle.
+	*/
+	static async delete(opts) {
+		const stream$1 = new DurableStream(opts);
+		return stream$1.delete();
+	}
+	/**
+	* HEAD metadata for this stream.
+	*/
+	async head(opts) {
+		const { requestHeaders, fetchUrl } = await this.#buildRequest();
+		const response = await this.#fetchClient(fetchUrl.toString(), {
+			method: `HEAD`,
+			headers: requestHeaders,
+			signal: opts?.signal ?? this.#options.signal
+		});
+		if (!response.ok) await handleErrorResponse(response, this.url);
+		const contentType = response.headers.get(`content-type`) ?? void 0;
+		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;
+		if (contentType) this.contentType = contentType;
+		return {
+			exists: true,
+			contentType,
+			offset,
+			etag,
+			cacheControl
+		};
+	}
+	/**
+	* Create this stream (create-only PUT) using the URL/auth from the handle.
+	*/
+	async create(opts) {
+		const { requestHeaders, fetchUrl } = await this.#buildRequest();
+		const contentType = opts?.contentType ?? this.#options.contentType;
+		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;
+		const body = encodeBody(opts?.body);
+		const response = await this.#fetchClient(fetchUrl.toString(), {
+			method: `PUT`,
+			headers: requestHeaders,
+			body,
+			signal: this.#options.signal
+		});
+		if (!response.ok) await handleErrorResponse(response, this.url, { operation: `create` });
+		const responseContentType = response.headers.get(`content-type`);
+		if (responseContentType) this.contentType = responseContentType;
+		else if (contentType) this.contentType = contentType;
+		return this;
+	}
+	/**
+	* Delete this stream.
+	*/
+	async delete(opts) {
+		const { requestHeaders, fetchUrl } = await this.#buildRequest();
+		const response = await this.#fetchClient(fetchUrl.toString(), {
+			method: `DELETE`,
+			headers: requestHeaders,
+			signal: opts?.signal ?? this.#options.signal
+		});
+		if (!response.ok) await handleErrorResponse(response, this.url);
+	}
+	/**
+	* 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.
+	* - 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" });
+	*
+	* // Promise value - awaited before buffering
+	* await stream.append(fetchData());
+	* await stream.append(Promise.all([a, b, c]));
+	* ```
+	*/
+	async append(body, opts) {
+		const resolvedBody = isPromiseLike(body) ? await body : body;
+		if (this.#batchingEnabled && this.#queue) return this.#appendWithBatching(resolvedBody, opts);
+		return this.#appendDirect(resolvedBody, opts);
+	}
+	/**
+	* Direct append without batching (used when batching is disabled).
+	*/
+	async #appendDirect(body, opts) {
+		const { requestHeaders, fetchUrl } = await this.#buildRequest();
+		const contentType = opts?.contentType ?? this.#options.contentType ?? this.contentType;
+		if (contentType) requestHeaders[`content-type`] = contentType;
+		if (opts?.seq) requestHeaders[STREAM_SEQ_HEADER] = opts.seq;
+		const isJson = normalizeContentType(contentType) === `application/json`;
+		const bodyToEncode = isJson ? [body] : body;
+		const encodedBody = encodeBody(bodyToEncode);
+		const response = await this.#fetchClient(fetchUrl.toString(), {
+			method: `POST`,
+			headers: requestHeaders,
+			body: encodedBody,
+			signal: opts?.signal ?? this.#options.signal
+		});
+		if (!response.ok) await handleErrorResponse(response, this.url);
+	}
+	/**
+	* Append with batching - buffers messages and sends them in batches.
+	*/
+	async #appendWithBatching(body, opts) {
+		return new Promise((resolve, reject) => {
+			this.#buffer.push({
+				data: body,
+				seq: opts?.seq,
+				contentType: opts?.contentType,
+				signal: opts?.signal,
+				resolve,
+				reject
+			});
+			if (this.#queue.idle()) {
+				const batch = this.#buffer.splice(0);
+				this.#queue.push(batch).catch((err) => {
+					for (const msg of batch) msg.reject(err);
+				});
+			}
+		});
+	}
+	/**
+	* Batch worker - processes batches of messages.
+	*/
+	async #batchWorker(batch) {
+		try {
+			await this.#sendBatch(batch);
+			for (const msg of batch) msg.resolve();
+			if (this.#buffer.length > 0) {
+				const nextBatch = this.#buffer.splice(0);
+				this.#queue.push(nextBatch).catch((err) => {
+					for (const msg of nextBatch) msg.reject(err);
+				});
+			}
+		} catch (error) {
+			for (const msg of batch) msg.reject(error);
+			for (const msg of this.#buffer) msg.reject(error);
+			this.#buffer = [];
+			throw error;
+		}
+	}
+	/**
+	* Send a batch of messages as a single POST request.
+	*/
+	async #sendBatch(batch) {
+		if (batch.length === 0) return;
+		const { requestHeaders, fetchUrl } = await this.#buildRequest();
+		const contentType = batch[0]?.contentType ?? this.#options.contentType ?? this.contentType;
+		if (contentType) requestHeaders[`content-type`] = contentType;
+		let highestSeq;
+		for (let i = batch.length - 1; i >= 0; i--) if (batch[i].seq !== void 0) {
+			highestSeq = batch[i].seq;
+			break;
+		}
+		if (highestSeq) requestHeaders[STREAM_SEQ_HEADER] = highestSeq;
+		const isJson = normalizeContentType(contentType) === `application/json`;
+		let batchedBody;
+		if (isJson) {
+			const values = batch.map((m) => m.data);
+			batchedBody = JSON.stringify(values);
+		} else {
+			const totalSize = batch.reduce((sum, m) => {
+				const size = typeof m.data === `string` ? new TextEncoder().encode(m.data).length : m.data.length;
+				return sum + size;
+			}, 0);
+			const concatenated = new Uint8Array(totalSize);
+			let offset = 0;
+			for (const msg of batch) {
+				const bytes = typeof msg.data === `string` ? new TextEncoder().encode(msg.data) : msg.data;
+				concatenated.set(bytes, offset);
+				offset += bytes.length;
+			}
+			batchedBody = concatenated;
+		}
+		const signals = [];
+		if (this.#options.signal) signals.push(this.#options.signal);
+		for (const msg of batch) if (msg.signal) signals.push(msg.signal);
+		const combinedSignal = signals.length > 0 ? AbortSignal.any(signals) : void 0;
+		const response = await this.#fetchClient(fetchUrl.toString(), {
+			method: `POST`,
+			headers: requestHeaders,
+			body: batchedBody,
+			signal: combinedSignal
+		});
+		if (!response.ok) await handleErrorResponse(response, this.url);
+	}
+	/**
+	* Append a streaming body to the stream.
+	*
+	* Supports piping from any ReadableStream or async iterable:
+	* - `source` yields Uint8Array or string chunks.
+	* - Strings are encoded as UTF-8; no delimiters are added.
+	* - Internally uses chunked transfer or HTTP/2 streaming.
+	*
+	* @example
+	* ```typescript
+	* // Pipe from a ReadableStream
+	* const readable = new ReadableStream({
+	*   start(controller) {
+	*     controller.enqueue("chunk 1");
+	*     controller.enqueue("chunk 2");
+	*     controller.close();
+	*   }
+	* });
+	* await stream.appendStream(readable);
+	*
+	* // Pipe from an async generator
+	* async function* generate() {
+	*   yield "line 1\n";
+	*   yield "line 2\n";
+	* }
+	* await stream.appendStream(generate());
+	*
+	* // Pipe from fetch response body
+	* const response = await fetch("https://example.com/data");
+	* await stream.appendStream(response.body!);
+	* ```
+	*/
+	async appendStream(source, opts) {
+		const { requestHeaders, fetchUrl } = await this.#buildRequest();
+		const contentType = opts?.contentType ?? this.#options.contentType ?? this.contentType;
+		if (contentType) requestHeaders[`content-type`] = contentType;
+		if (opts?.seq) requestHeaders[STREAM_SEQ_HEADER] = opts.seq;
+		const body = toReadableStream(source);
+		const response = await this.#fetchClient(fetchUrl.toString(), {
+			method: `POST`,
+			headers: requestHeaders,
+			body,
+			duplex: `half`,
+			signal: opts?.signal ?? this.#options.signal
+		});
+		if (!response.ok) await handleErrorResponse(response, this.url);
+	}
+	/**
+	* Create a writable stream that pipes data to this durable stream.
+	*
+	* Returns a WritableStream that can be used with `pipeTo()` or
+	* `pipeThrough()` from any ReadableStream source.
+	*
+	* @example
+	* ```typescript
+	* // Pipe from fetch response
+	* const response = await fetch("https://example.com/data");
+	* await response.body!.pipeTo(stream.writable());
+	*
+	* // Pipe through a transform
+	* const readable = someStream.pipeThrough(new TextEncoderStream());
+	* await readable.pipeTo(stream.writable());
+	* ```
+	*/
+	writable(opts) {
+		const chunks = [];
+		const stream$1 = this;
+		return new WritableStream({
+			write(chunk) {
+				chunks.push(chunk);
+			},
+			async close() {
+				if (chunks.length > 0) {
+					const readable = new ReadableStream({ start(controller) {
+						for (const chunk of chunks) controller.enqueue(chunk);
+						controller.close();
+					} });
+					await stream$1.appendStream(readable, opts);
+				}
+			},
+			abort(reason) {
+				console.error(`WritableStream aborted:`, reason);
+			}
+		});
+	}
+	/**
+	* 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
+	* a valid first response, or rejects on errors.
+	*
+	* Call-specific headers and params are merged with handle-level ones,
+	* with call-specific values taking precedence.
+	*
+	* @example
+	* ```typescript
+	* const handle = await DurableStream.connect({
+	*   url,
+	*   headers: { Authorization: `Bearer ${token}` }
+	* });
+	* const res = await handle.stream<{ message: string }>();
+	*
+	* // Accumulate all JSON items
+	* const items = await res.json();
+	*
+	* // Or stream live with ReadableStream
+	* const reader = res.jsonStream().getReader();
+	* let result = await reader.read();
+	* while (!result.done) {
+	*   console.log(result.value);
+	*   result = await reader.read();
+	* }
+	*
+	* // Or use subscriber for backpressure-aware consumption
+	* res.subscribeJson(async (batch) => {
+	*   for (const item of batch.items) {
+	*     console.log(item);
+	*   }
+	* });
+	* ```
+	*/
+	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
+		};
+		const mergedParams = {
+			...this.#options.params,
+			...options?.params
+		};
+		return stream({
+			url: this.url,
+			headers: mergedHeaders,
+			params: mergedParams,
+			signal: options?.signal ?? this.#options.signal,
+			fetch: this.#options.fetch,
+			backoffOptions: this.#options.backoffOptions,
+			offset: options?.offset,
+			live: options?.live,
+			json: options?.json,
+			onError: options?.onError ?? this.#onError
+		});
+	}
+	/**
+	* Build request headers and URL.
+	*/
+	async #buildRequest() {
+		const requestHeaders = await resolveHeaders(this.#options.headers);
+		const fetchUrl = new URL(this.url);
+		const params = await resolveParams(this.#options.params);
+		for (const [key, value] of Object.entries(params)) fetchUrl.searchParams.set(key, value);
+		return {
+			requestHeaders,
+			fetchUrl
+		};
+	}
+};
+/**
+* Encode a body value to the appropriate format.
+* Strings are encoded as UTF-8.
+* Objects are JSON-serialized.
+*/
+function encodeBody(body) {
+	if (body === void 0) return void 0;
+	if (typeof body === `string`) return new TextEncoder().encode(body);
+	if (body instanceof Uint8Array) return body;
+	if (body instanceof Blob || body instanceof FormData || body instanceof ReadableStream || body instanceof ArrayBuffer || ArrayBuffer.isView(body)) return body;
+	return new TextEncoder().encode(JSON.stringify(body));
+}
+/**
+* Convert an async iterable to a ReadableStream.
+*/
+function toReadableStream(source) {
+	if (source instanceof ReadableStream) return source.pipeThrough(new TransformStream({ transform(chunk, controller) {
+		if (typeof chunk === `string`) controller.enqueue(new TextEncoder().encode(chunk));
+		else controller.enqueue(chunk);
+	} }));
+	const encoder = new TextEncoder();
+	const iterator = source[Symbol.asyncIterator]();
+	return new ReadableStream({
+		async pull(controller) {
+			try {
+				const { done, value } = await iterator.next();
+				if (done) controller.close();
+				else if (typeof value === `string`) controller.enqueue(encoder.encode(value));
+				else controller.enqueue(value);
+			} catch (e) {
+				controller.error(e);
+			}
+		},
+		cancel() {
+			iterator.return?.();
+		}
+	});
+}
+/**
+* Validate stream options.
+*/
+function validateOptions(options) {
+	if (!options.url) throw new MissingStreamUrlError();
+	if (options.signal && !(options.signal instanceof AbortSignal)) throw new InvalidSignalError();
+}
+
+//#endregion
+exports.BackoffDefaults = BackoffDefaults
+exports.CURSOR_QUERY_PARAM = CURSOR_QUERY_PARAM
+exports.DURABLE_STREAM_PROTOCOL_QUERY_PARAMS = DURABLE_STREAM_PROTOCOL_QUERY_PARAMS
+exports.DurableStream = DurableStream
+exports.DurableStreamError = DurableStreamError
+exports.FetchBackoffAbortError = FetchBackoffAbortError
+exports.FetchError = FetchError
+exports.InvalidSignalError = InvalidSignalError
+exports.LIVE_QUERY_PARAM = LIVE_QUERY_PARAM
+exports.MissingStreamUrlError = MissingStreamUrlError
+exports.OFFSET_QUERY_PARAM = OFFSET_QUERY_PARAM
+exports.SSE_COMPATIBLE_CONTENT_TYPES = SSE_COMPATIBLE_CONTENT_TYPES
+exports.STREAM_CURSOR_HEADER = STREAM_CURSOR_HEADER
+exports.STREAM_EXPIRES_AT_HEADER = STREAM_EXPIRES_AT_HEADER
+exports.STREAM_OFFSET_HEADER = STREAM_OFFSET_HEADER
+exports.STREAM_SEQ_HEADER = STREAM_SEQ_HEADER
+exports.STREAM_TTL_HEADER = STREAM_TTL_HEADER
+exports.STREAM_UP_TO_DATE_HEADER = STREAM_UP_TO_DATE_HEADER
+exports.asAsyncIterableReadableStream = asAsyncIterableReadableStream
+exports.createFetchWithBackoff = createFetchWithBackoff
+exports.createFetchWithConsumedBody = createFetchWithConsumedBody
+exports.stream = stream