@durable-streams/client 0.1.5 → 0.2.0

package/dist/index.cjs

@@ -506,7 +506,10 @@ async function* parseSSEStream(stream$1, signal) {
 							streamCursor: control.streamCursor,
 							upToDate: control.upToDate
 						};
-					} catch {}
+					} catch (err) {
+						const preview = dataStr.length > 100 ? dataStr.slice(0, 100) + `...` : dataStr;
+						throw new DurableStreamError(`Failed to parse SSE control event: ${err instanceof Error ? err.message : String(err)}. Data: ${preview}`, `PARSE_ERROR`);
+					}
 				}
 				currentEvent = { data: [] };
 			} else if (line.startsWith(`event:`)) currentEvent.type = line.slice(6).trim();
@@ -531,7 +534,10 @@ async function* parseSSEStream(stream$1, signal) {
 					streamCursor: control.streamCursor,
 					upToDate: control.upToDate
 				};
-			} catch {}
+			} catch (err) {
+				const preview = dataStr.length > 100 ? dataStr.slice(0, 100) + `...` : dataStr;
+				throw new DurableStreamError(`Failed to parse SSE control event: ${err instanceof Error ? err.message : String(err)}. Data: ${preview}`, `PARSE_ERROR`);
+			}
 		}
 	} finally {
 		reader.releaseLock();
@@ -557,9 +563,9 @@ var StreamResponseImpl = class {
 	#statusText;
 	#ok;
 	#isLoading;
-	offset;
-	cursor;
-	upToDate;
+	#offset;
+	#cursor;
+	#upToDate;
 	#isJsonMode;
 	#abortController;
 	#fetchNext;
@@ -585,9 +591,9 @@ var StreamResponseImpl = class {
 		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.#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;
@@ -678,6 +684,15 @@ var StreamResponseImpl = class {
 	get isLoading() {
 		return this.#isLoading;
 	}
+	get offset() {
+		return this.#offset;
+	}
+	get cursor() {
+		return this.#cursor;
+	}
+	get upToDate() {
+		return this.#upToDate;
+	}
 	#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`);
 	}
@@ -711,10 +726,10 @@ var StreamResponseImpl = class {
 	*/
 	#updateStateFromResponse(response) {
 		const offset = response.headers.get(STREAM_OFFSET_HEADER);
-		if (offset) this.offset = offset;
+		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);
+		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;
@@ -756,9 +771,9 @@ var StreamResponseImpl = class {
 	* 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.#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.
@@ -1024,7 +1039,13 @@ var StreamResponseImpl = class {
 				const wasUpToDate = this.upToDate;
 				const text = await result.value.text();
 				const content = text.trim() || `[]`;
-				const parsed = JSON.parse(content);
+				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`);
+				}
 				if (Array.isArray(parsed)) items.push(...parsed);
 				else items.push(parsed);
 				if (wasUpToDate) break;
@@ -1121,7 +1142,13 @@ var StreamResponseImpl = class {
 				}
 				const text = await response.text();
 				const content = text.trim() || `[]`;
-				const parsed = JSON.parse(content);
+				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());
 			},
@@ -1160,7 +1187,13 @@ var StreamResponseImpl = class {
 					const { offset, cursor, upToDate } = this.#getMetadataFromResponse(response);
 					const text = await response.text();
 					const content = text.trim() || `[]`;
-					const parsed = JSON.parse(content);
+					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`);
+					}
 					const items = Array.isArray(parsed) ? parsed : [parsed];
 					await subscriber({
 						items,
@@ -1405,7 +1438,7 @@ function _resetHttpWarningForTesting() {
 *   url,
 *   auth,
 *   offset: savedOffset,
-*   live: "auto",
+*   live: true,
 * })
 * live.subscribeJson(async (batch) => {
 *   for (const item of batch.items) {
@@ -1446,10 +1479,11 @@ async function stream(options) {
 */
 async function streamInternal(options) {
 	const url = options.url instanceof URL ? options.url.toString() : options.url;
+	warnIfUsingHttpInBrowser(url, options.warnOnHttp);
 	const fetchUrl = new URL(url);
 	const startOffset = options.offset ?? `-1`;
 	fetchUrl.searchParams.set(OFFSET_QUERY_PARAM, startOffset);
-	const live = options.live ?? `auto`;
+	const live = options.live ?? true;
 	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);
@@ -1479,8 +1513,8 @@ async function streamInternal(options) {
 		const nextUrl = new URL(url);
 		nextUrl.searchParams.set(OFFSET_QUERY_PARAM, offset);
 		if (!resumingFromPause) {
-			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 (live === `sse`) nextUrl.searchParams.set(LIVE_QUERY_PARAM, `sse`);
+			else if (live === true || live === `long-poll`) nextUrl.searchParams.set(LIVE_QUERY_PARAM, `long-poll`);
 		}
 		if (cursor) nextUrl.searchParams.set(`cursor`, cursor);
 		const nextParams = await resolveParams(options.params);
@@ -1528,405 +1562,822 @@ async function streamInternal(options) {
 }
 
 //#endregion
-//#region src/stream.ts
+//#region src/idempotent-producer.ts
+/**
+* Error thrown when a producer's epoch is stale (zombie fencing).
+*/
+var StaleEpochError = class extends Error {
+	/**
+	* The current epoch on the server.
+	*/
+	currentEpoch;
+	constructor(currentEpoch) {
+		super(`Producer epoch is stale. Current server epoch: ${currentEpoch}. Call restart() or create a new producer with a higher epoch.`);
+		this.name = `StaleEpochError`;
+		this.currentEpoch = currentEpoch;
+	}
+};
+/**
+* Error thrown when an unrecoverable sequence gap is detected.
+*
+* With maxInFlight > 1, HTTP requests can arrive out of order at the server,
+* causing temporary 409 responses. The client automatically handles these
+* by waiting for earlier sequences to complete, then retrying.
+*
+* This error is only thrown when the gap cannot be resolved (e.g., the
+* expected sequence is >= our sequence, indicating a true protocol violation).
+*/
+var SequenceGapError = class extends Error {
+	expectedSeq;
+	receivedSeq;
+	constructor(expectedSeq, receivedSeq) {
+		super(`Producer sequence gap: expected ${expectedSeq}, received ${receivedSeq}`);
+		this.name = `SequenceGapError`;
+		this.expectedSeq = expectedSeq;
+		this.receivedSeq = receivedSeq;
+	}
+};
 /**
 * Normalize content-type by extracting the media type (before any semicolon).
-* Handles cases like "application/json; charset=utf-8".
 */
 function normalizeContentType$1(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.
+* An idempotent producer for exactly-once writes to a durable stream.
 *
-* This is a lightweight, reusable handle - not a persistent connection.
-* It does not automatically start reading or listening.
-* Create sessions as needed via stream().
+* Features:
+* - Fire-and-forget: append() returns immediately, batches in background
+* - Exactly-once: server deduplicates using (producerId, epoch, seq)
+* - Batching: multiple appends batched into single HTTP request
+* - Pipelining: up to maxInFlight concurrent batches
+* - Zombie fencing: stale producers rejected via epoch validation
 *
 * @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"
+* const stream = new DurableStream({ url: "https://..." });
+* const producer = new IdempotentProducer(stream, "order-service-1", {
+*   epoch: 0,
+*   autoClaim: true,
 * });
 *
-* // Write data
-* await stream.append({ message: "hello" });
+* // Fire-and-forget writes (synchronous, returns immediately)
+* producer.append("message 1");
+* producer.append("message 2");
 *
-* // 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);
-*   }
-* });
+* // Ensure all messages are delivered before shutdown
+* await producer.flush();
+* await producer.close();
 * ```
 */
-var DurableStream = class DurableStream {
-	/**
-	* The URL of the durable stream.
-	*/
-	url;
-	/**
-	* The content type of the stream (populated after connect/head/read).
-	*/
-	contentType;
-	#options;
+var IdempotentProducer = class {
+	#stream;
+	#producerId;
+	#epoch;
+	#nextSeq = 0;
+	#autoClaim;
+	#maxBatchBytes;
+	#lingerMs;
 	#fetchClient;
+	#signal;
 	#onError;
-	#batchingEnabled;
+	#pendingBatch = [];
+	#batchBytes = 0;
+	#lingerTimeout = null;
 	#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;
-		if (opts.contentType) this.contentType = opts.contentType;
-		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);
-	}
+	#maxInFlight;
+	#closed = false;
+	#epochClaimed;
+	#seqState = new Map();
 	/**
-	* Create a new stream (create-only PUT) and return a handle.
-	* Fails with DurableStreamError(code="CONFLICT_EXISTS") if it already exists.
+	* Create an idempotent producer for a stream.
+	*
+	* @param stream - The DurableStream to write to
+	* @param producerId - Stable identifier for this producer (e.g., "order-service-1")
+	* @param opts - Producer options
 	*/
-	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;
+	constructor(stream$1, producerId, opts) {
+		const epoch = opts?.epoch ?? 0;
+		const maxBatchBytes = opts?.maxBatchBytes ?? 1024 * 1024;
+		const maxInFlight = opts?.maxInFlight ?? 5;
+		const lingerMs = opts?.lingerMs ?? 5;
+		if (epoch < 0) throw new Error(`epoch must be >= 0`);
+		if (maxBatchBytes <= 0) throw new Error(`maxBatchBytes must be > 0`);
+		if (maxInFlight <= 0) throw new Error(`maxInFlight must be > 0`);
+		if (lingerMs < 0) throw new Error(`lingerMs must be >= 0`);
+		this.#stream = stream$1;
+		this.#producerId = producerId;
+		this.#epoch = epoch;
+		this.#autoClaim = opts?.autoClaim ?? false;
+		this.#maxBatchBytes = maxBatchBytes;
+		this.#lingerMs = lingerMs;
+		this.#signal = opts?.signal;
+		this.#onError = opts?.onError;
+		this.#fetchClient = opts?.fetch ?? ((...args) => fetch(...args));
+		this.#maxInFlight = maxInFlight;
+		this.#epochClaimed = !this.#autoClaim;
+		this.#queue = fastq.default.promise(this.#batchWorker.bind(this), this.#maxInFlight);
+		if (this.#signal) this.#signal.addEventListener(`abort`, () => {
+			this.#rejectPendingBatch(new DurableStreamError(`Producer aborted`, `ALREADY_CLOSED`, void 0, void 0));
+		}, { once: true });
 	}
 	/**
-	* Validate that a stream exists and fetch metadata via HEAD.
-	* Returns a handle with contentType populated (if sent by server).
+	* Append data to the stream.
 	*
-	* **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.
+	* This is fire-and-forget: returns immediately after adding to the batch.
+	* The message is batched and sent when:
+	* - maxBatchBytes is reached
+	* - lingerMs elapses
+	* - flush() is called
+	*
+	* Errors are reported via onError callback if configured. Use flush() to
+	* wait for all pending messages to be sent.
+	*
+	* For JSON streams, pass pre-serialized JSON strings.
+	* For byte streams, pass string or Uint8Array.
+	*
+	* @param body - Data to append (string or Uint8Array)
 	*
 	* @example
 	* ```typescript
-	* // Validate stream exists before reading
-	* const handle = await DurableStream.connect({ url })
-	* const res = await handle.stream() // Now actually read
+	* // JSON stream
+	* producer.append(JSON.stringify({ message: "hello" }));
+	*
+	* // Byte stream
+	* producer.append("raw text data");
+	* producer.append(new Uint8Array([1, 2, 3]));
 	* ```
 	*/
-	static async connect(opts) {
-		const stream$1 = new DurableStream(opts);
-		await stream$1.head();
-		return stream$1;
+	append(body) {
+		if (this.#closed) throw new DurableStreamError(`Producer is closed`, `ALREADY_CLOSED`, void 0, void 0);
+		let bytes;
+		if (typeof body === `string`) bytes = new TextEncoder().encode(body);
+		else if (body instanceof Uint8Array) bytes = body;
+		else throw new DurableStreamError(`append() requires string or Uint8Array. For objects, use JSON.stringify().`, `BAD_REQUEST`, 400, void 0);
+		this.#pendingBatch.push({ body: bytes });
+		this.#batchBytes += bytes.length;
+		if (this.#batchBytes >= this.#maxBatchBytes) this.#enqueuePendingBatch();
+		else if (!this.#lingerTimeout) this.#lingerTimeout = setTimeout(() => {
+			this.#lingerTimeout = null;
+			if (this.#pendingBatch.length > 0) this.#enqueuePendingBatch();
+		}, this.#lingerMs);
 	}
 	/**
-	* HEAD metadata for a stream without creating a handle.
+	* Send any pending batch immediately and wait for all in-flight batches.
+	*
+	* Call this before shutdown to ensure all messages are delivered.
 	*/
-	static async head(opts) {
-		const stream$1 = new DurableStream(opts);
-		return stream$1.head();
+	async flush() {
+		if (this.#lingerTimeout) {
+			clearTimeout(this.#lingerTimeout);
+			this.#lingerTimeout = null;
+		}
+		if (this.#pendingBatch.length > 0) this.#enqueuePendingBatch();
+		await this.#queue.drained();
 	}
 	/**
-	* Delete a stream without creating a handle.
+	* Flush pending messages and close the producer.
+	*
+	* After calling close(), further append() calls will throw.
 	*/
-	static async delete(opts) {
-		const stream$1 = new DurableStream(opts);
-		return stream$1.delete();
+	async close() {
+		if (this.#closed) return;
+		this.#closed = true;
+		try {
+			await this.flush();
+		} catch {}
 	}
 	/**
-	* HEAD metadata for this stream.
+	* Increment epoch and reset sequence.
+	*
+	* Call this when restarting the producer to establish a new session.
+	* Flushes any pending messages first.
 	*/
-	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 restart() {
+		await this.flush();
+		this.#epoch++;
+		this.#nextSeq = 0;
+	}
+	/**
+	* Current epoch for this producer.
 	*/
-	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;
+	get epoch() {
+		return this.#epoch;
 	}
 	/**
-	* Delete this stream.
+	* Next sequence number to be assigned.
 	*/
-	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);
+	get nextSeq() {
+		return this.#nextSeq;
 	}
 	/**
-	* 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]));
-	* ```
+	* Number of messages in the current pending batch.
 	*/
-	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);
+	get pendingCount() {
+		return this.#pendingBatch.length;
 	}
 	/**
-	* Direct append without batching (used when batching is disabled).
+	* Number of batches currently in flight.
 	*/
-	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$1(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);
+	get inFlightCount() {
+		return this.#queue.length();
 	}
 	/**
-	* Append with batching - buffers messages and sends them in batches.
+	* Enqueue the current pending batch for processing.
 	*/
-	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);
-				});
-			}
+	#enqueuePendingBatch() {
+		if (this.#pendingBatch.length === 0) return;
+		const batch = this.#pendingBatch;
+		const seq = this.#nextSeq;
+		this.#pendingBatch = [];
+		this.#batchBytes = 0;
+		this.#nextSeq++;
+		if (this.#autoClaim && !this.#epochClaimed && this.#queue.length() > 0) this.#queue.drained().then(() => {
+			this.#queue.push({
+				batch,
+				seq
+			}).catch(() => {});
 		});
+		else this.#queue.push({
+			batch,
+			seq
+		}).catch(() => {});
 	}
 	/**
-	* Batch worker - processes batches of messages.
+	* Batch worker - processes batches via fastq.
 	*/
-	async #batchWorker(batch) {
+	async #batchWorker(task) {
+		const { batch, seq } = task;
+		const epoch = this.#epoch;
 		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);
-				});
-			}
+			await this.#doSendBatch(batch, seq, epoch);
+			if (!this.#epochClaimed) this.#epochClaimed = true;
+			this.#signalSeqComplete(epoch, seq, void 0);
 		} catch (error) {
-			for (const msg of batch) msg.reject(error);
-			for (const msg of this.#buffer) msg.reject(error);
-			this.#buffer = [];
+			this.#signalSeqComplete(epoch, seq, error);
+			if (this.#onError) this.#onError(error);
 			throw error;
 		}
 	}
 	/**
-	* Send a batch of messages as a single POST request.
+	* Signal that a sequence has completed (success or failure).
 	*/
-	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;
+	#signalSeqComplete(epoch, seq, error) {
+		let epochMap = this.#seqState.get(epoch);
+		if (!epochMap) {
+			epochMap = new Map();
+			this.#seqState.set(epoch, epochMap);
 		}
-		if (highestSeq) requestHeaders[STREAM_SEQ_HEADER] = highestSeq;
+		const state = epochMap.get(seq);
+		if (state) {
+			state.resolved = true;
+			state.error = error;
+			for (const waiter of state.waiters) waiter(error);
+			state.waiters = [];
+		} else epochMap.set(seq, {
+			resolved: true,
+			error,
+			waiters: []
+		});
+		const cleanupThreshold = seq - this.#maxInFlight * 3;
+		if (cleanupThreshold > 0) {
+			for (const oldSeq of epochMap.keys()) if (oldSeq < cleanupThreshold) epochMap.delete(oldSeq);
+		}
+	}
+	/**
+	* Wait for a specific sequence to complete.
+	* Returns immediately if already completed.
+	* Throws if the sequence failed.
+	*/
+	#waitForSeq(epoch, seq) {
+		let epochMap = this.#seqState.get(epoch);
+		if (!epochMap) {
+			epochMap = new Map();
+			this.#seqState.set(epoch, epochMap);
+		}
+		const state = epochMap.get(seq);
+		if (state?.resolved) {
+			if (state.error) return Promise.reject(state.error);
+			return Promise.resolve();
+		}
+		return new Promise((resolve, reject) => {
+			const waiter = (err) => {
+				if (err) reject(err);
+				else resolve();
+			};
+			if (state) state.waiters.push(waiter);
+			else epochMap.set(seq, {
+				resolved: false,
+				waiters: [waiter]
+			});
+		});
+	}
+	/**
+	* Actually send the batch to the server.
+	* Handles auto-claim retry on 403 (stale epoch) if autoClaim is enabled.
+	* Does NOT implement general retry/backoff for network errors or 5xx responses.
+	*/
+	async #doSendBatch(batch, seq, epoch) {
+		const contentType = this.#stream.contentType ?? `application/octet-stream`;
 		const isJson = normalizeContentType$1(contentType) === `application/json`;
 		let batchedBody;
 		if (isJson) {
-			const values = batch.map((m) => m.data);
-			batchedBody = JSON.stringify(values);
+			const jsonStrings = batch.map((e) => new TextDecoder().decode(e.body));
+			batchedBody = `[${jsonStrings.join(`,`)}]`;
 		} 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 totalSize = batch.reduce((sum, e) => sum + e.body.length, 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;
+			for (const entry of batch) {
+				concatenated.set(entry.body, offset);
+				offset += entry.body.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(), {
+		const url = this.#stream.url;
+		const headers = {
+			"content-type": contentType,
+			[PRODUCER_ID_HEADER]: this.#producerId,
+			[PRODUCER_EPOCH_HEADER]: epoch.toString(),
+			[PRODUCER_SEQ_HEADER]: seq.toString()
+		};
+		const response = await this.#fetchClient(url, {
 			method: `POST`,
-			headers: requestHeaders,
+			headers,
 			body: batchedBody,
-			signal: combinedSignal
+			signal: this.#signal
 		});
-		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!);
+		if (response.status === 204) return {
+			offset: ``,
+			duplicate: true
+		};
+		if (response.status === 200) {
+			const resultOffset = response.headers.get(STREAM_OFFSET_HEADER) ?? ``;
+			return {
+				offset: resultOffset,
+				duplicate: false
+			};
+		}
+		if (response.status === 403) {
+			const currentEpochStr = response.headers.get(PRODUCER_EPOCH_HEADER);
+			const currentEpoch = currentEpochStr ? parseInt(currentEpochStr, 10) : epoch;
+			if (this.#autoClaim) {
+				const newEpoch = currentEpoch + 1;
+				this.#epoch = newEpoch;
+				this.#nextSeq = 1;
+				return this.#doSendBatch(batch, 0, newEpoch);
+			}
+			throw new StaleEpochError(currentEpoch);
+		}
+		if (response.status === 409) {
+			const expectedSeqStr = response.headers.get(PRODUCER_EXPECTED_SEQ_HEADER);
+			const expectedSeq = expectedSeqStr ? parseInt(expectedSeqStr, 10) : 0;
+			if (expectedSeq < seq) {
+				const waitPromises = [];
+				for (let s = expectedSeq; s < seq; s++) waitPromises.push(this.#waitForSeq(epoch, s));
+				await Promise.all(waitPromises);
+				return this.#doSendBatch(batch, seq, epoch);
+			}
+			const receivedSeqStr = response.headers.get(PRODUCER_RECEIVED_SEQ_HEADER);
+			const receivedSeq = receivedSeqStr ? parseInt(receivedSeqStr, 10) : seq;
+			throw new SequenceGapError(expectedSeq, receivedSeq);
+		}
+		if (response.status === 400) {
+			const error$1 = await DurableStreamError.fromResponse(response, url);
+			throw error$1;
+		}
+		const error = await FetchError.fromResponse(response, url);
+		throw error;
+	}
+	/**
+	* Clear pending batch and report error.
+	*/
+	#rejectPendingBatch(error) {
+		if (this.#onError && this.#pendingBatch.length > 0) this.#onError(error);
+		this.#pendingBatch = [];
+		this.#batchBytes = 0;
+		if (this.#lingerTimeout) {
+			clearTimeout(this.#lingerTimeout);
+			this.#lingerTimeout = null;
+		}
+	}
+};
+
+//#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.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(JSON.stringify({ 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;
+		if (opts.contentType) this.contentType = opts.contentType;
+		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
 	* ```
 	*/
-	async appendStream(source, opts) {
+	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 contentType = opts?.contentType ?? this.#options.contentType ?? this.contentType;
+		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?.seq) requestHeaders[STREAM_SEQ_HEADER] = opts.seq;
-		const body = toReadableStream(source);
+		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: `POST`,
+			method: `PUT`,
 			headers: requestHeaders,
 			body,
-			duplex: `half`,
+			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);
 	}
 	/**
-	* Create a writable stream that pipes data to this durable stream.
+	* Append a single payload to the stream.
 	*
-	* Returns a WritableStream that can be used with `pipeTo()` or
-	* `pipeThrough()` from any ReadableStream source.
+	* 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` must be string or Uint8Array.
+	* - For JSON streams, pass pre-serialized JSON strings.
+	* - `body` may also be a Promise that resolves to string or Uint8Array.
+	* - Strings are encoded as UTF-8.
+	* - `seq` (if provided) is sent as stream-seq (writer coordination).
 	*
 	* @example
 	* ```typescript
-	* // Pipe from fetch response
-	* const response = await fetch("https://example.com/data");
-	* await response.body!.pipeTo(stream.writable());
+	* // JSON stream - pass pre-serialized JSON
+	* await stream.append(JSON.stringify({ message: "hello" }));
 	*
-	* // Pipe through a transform
-	* const readable = someStream.pipeThrough(new TextEncoderStream());
-	* await readable.pipeTo(stream.writable());
+	* // Byte stream
+	* await stream.append("raw text data");
+	* await stream.append(new Uint8Array([1, 2, 3]));
+	*
+	* // Promise value - awaited before buffering
+	* await stream.append(fetchData());
 	* ```
 	*/
-	writable(opts) {
-		const chunks = [];
-		const stream$1 = this;
-		return new WritableStream({
+	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 bodyStr = typeof body === `string` ? body : new TextDecoder().decode(body);
+		const encodedBody = isJson ? `[${bodyStr}]` : bodyStr;
+		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 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 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.
+	*
+	* Uses IdempotentProducer internally for:
+	* - Automatic batching (controlled by lingerMs, maxBatchBytes)
+	* - Exactly-once delivery semantics
+	* - Streaming writes (doesn't buffer entire content in memory)
+	*
+	* @example
+	* ```typescript
+	* // Pipe from fetch response
+	* 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());
+	*
+	* // With custom producer options
+	* await source.pipeTo(stream.writable({
+	*   producerId: "my-producer",
+	*   lingerMs: 10,
+	*   maxBatchBytes: 64 * 1024,
+	* }));
+	* ```
+	*/
+	writable(opts) {
+		const producerId = opts?.producerId ?? `writable-${crypto.randomUUID().slice(0, 8)}`;
+		let writeError = null;
+		const producer = new IdempotentProducer(this, producerId, {
+			autoClaim: true,
+			lingerMs: opts?.lingerMs,
+			maxBatchBytes: opts?.maxBatchBytes,
+			onError: (error) => {
+				if (!writeError) writeError = error;
+				opts?.onError?.(error);
+			},
+			signal: opts?.signal ?? this.#options.signal
+		});
+		return new WritableStream({
 			write(chunk) {
-				chunks.push(chunk);
+				producer.append(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);
-				}
+				await producer.flush();
+				await producer.close();
+				if (writeError) throw writeError;
 			},
-			abort(reason) {
-				console.error(`WritableStream aborted:`, reason);
+			abort(_reason) {
+				producer.close().catch((err) => {
+					opts?.onError?.(err);
+				});
 			}
 		});
 	}
@@ -2053,403 +2504,6 @@ function validateOptions(options) {
 	warnIfUsingHttpInBrowser(options.url, options.warnOnHttp);
 }
 
-//#endregion
-//#region src/idempotent-producer.ts
-/**
-* Error thrown when a producer's epoch is stale (zombie fencing).
-*/
-var StaleEpochError = class extends Error {
-	/**
-	* The current epoch on the server.
-	*/
-	currentEpoch;
-	constructor(currentEpoch) {
-		super(`Producer epoch is stale. Current server epoch: ${currentEpoch}. Call restart() or create a new producer with a higher epoch.`);
-		this.name = `StaleEpochError`;
-		this.currentEpoch = currentEpoch;
-	}
-};
-/**
-* Error thrown when an unrecoverable sequence gap is detected.
-*
-* With maxInFlight > 1, HTTP requests can arrive out of order at the server,
-* causing temporary 409 responses. The client automatically handles these
-* by waiting for earlier sequences to complete, then retrying.
-*
-* This error is only thrown when the gap cannot be resolved (e.g., the
-* expected sequence is >= our sequence, indicating a true protocol violation).
-*/
-var SequenceGapError = class extends Error {
-	expectedSeq;
-	receivedSeq;
-	constructor(expectedSeq, receivedSeq) {
-		super(`Producer sequence gap: expected ${expectedSeq}, received ${receivedSeq}`);
-		this.name = `SequenceGapError`;
-		this.expectedSeq = expectedSeq;
-		this.receivedSeq = receivedSeq;
-	}
-};
-/**
-* Normalize content-type by extracting the media type (before any semicolon).
-*/
-function normalizeContentType(contentType) {
-	if (!contentType) return ``;
-	return contentType.split(`;`)[0].trim().toLowerCase();
-}
-/**
-* An idempotent producer for exactly-once writes to a durable stream.
-*
-* Features:
-* - Fire-and-forget: append() returns immediately, batches in background
-* - Exactly-once: server deduplicates using (producerId, epoch, seq)
-* - Batching: multiple appends batched into single HTTP request
-* - Pipelining: up to maxInFlight concurrent batches
-* - Zombie fencing: stale producers rejected via epoch validation
-*
-* @example
-* ```typescript
-* const stream = new DurableStream({ url: "https://..." });
-* const producer = new IdempotentProducer(stream, "order-service-1", {
-*   epoch: 0,
-*   autoClaim: true,
-* });
-*
-* // Fire-and-forget writes (synchronous, returns immediately)
-* producer.append("message 1");
-* producer.append("message 2");
-*
-* // Ensure all messages are delivered before shutdown
-* await producer.flush();
-* await producer.close();
-* ```
-*/
-var IdempotentProducer = class {
-	#stream;
-	#producerId;
-	#epoch;
-	#nextSeq = 0;
-	#autoClaim;
-	#maxBatchBytes;
-	#lingerMs;
-	#fetchClient;
-	#signal;
-	#onError;
-	#pendingBatch = [];
-	#batchBytes = 0;
-	#lingerTimeout = null;
-	#queue;
-	#maxInFlight;
-	#closed = false;
-	#epochClaimed;
-	#seqState = new Map();
-	/**
-	* Create an idempotent producer for a stream.
-	*
-	* @param stream - The DurableStream to write to
-	* @param producerId - Stable identifier for this producer (e.g., "order-service-1")
-	* @param opts - Producer options
-	*/
-	constructor(stream$1, producerId, opts) {
-		this.#stream = stream$1;
-		this.#producerId = producerId;
-		this.#epoch = opts?.epoch ?? 0;
-		this.#autoClaim = opts?.autoClaim ?? false;
-		this.#maxBatchBytes = opts?.maxBatchBytes ?? 1024 * 1024;
-		this.#lingerMs = opts?.lingerMs ?? 5;
-		this.#signal = opts?.signal;
-		this.#onError = opts?.onError;
-		this.#fetchClient = opts?.fetch ?? ((...args) => fetch(...args));
-		this.#maxInFlight = opts?.maxInFlight ?? 5;
-		this.#epochClaimed = !this.#autoClaim;
-		this.#queue = fastq.default.promise(this.#batchWorker.bind(this), this.#maxInFlight);
-		if (this.#signal) this.#signal.addEventListener(`abort`, () => {
-			this.#rejectPendingBatch(new DurableStreamError(`Producer aborted`, `ALREADY_CLOSED`, void 0, void 0));
-		}, { once: true });
-	}
-	/**
-	* Append data to the stream.
-	*
-	* This is fire-and-forget: returns immediately after adding to the batch.
-	* The message is batched and sent when:
-	* - maxBatchBytes is reached
-	* - lingerMs elapses
-	* - flush() is called
-	*
-	* Errors are reported via onError callback if configured. Use flush() to
-	* wait for all pending messages to be sent.
-	*
-	* For JSON streams, pass native objects (which will be serialized internally).
-	* For byte streams, pass string or Uint8Array.
-	*
-	* @param body - Data to append (object for JSON streams, string or Uint8Array for byte streams)
-	*/
-	append(body) {
-		if (this.#closed) throw new DurableStreamError(`Producer is closed`, `ALREADY_CLOSED`, void 0, void 0);
-		const isJson = normalizeContentType(this.#stream.contentType) === `application/json`;
-		let bytes;
-		let data;
-		if (isJson) {
-			const json = JSON.stringify(body);
-			bytes = new TextEncoder().encode(json);
-			data = body;
-		} else {
-			if (typeof body === `string`) bytes = new TextEncoder().encode(body);
-			else if (body instanceof Uint8Array) bytes = body;
-			else throw new DurableStreamError(`Non-JSON streams require string or Uint8Array`, `BAD_REQUEST`, 400, void 0);
-			data = bytes;
-		}
-		this.#pendingBatch.push({
-			data,
-			body: bytes
-		});
-		this.#batchBytes += bytes.length;
-		if (this.#batchBytes >= this.#maxBatchBytes) this.#enqueuePendingBatch();
-		else if (!this.#lingerTimeout) this.#lingerTimeout = setTimeout(() => {
-			this.#lingerTimeout = null;
-			if (this.#pendingBatch.length > 0) this.#enqueuePendingBatch();
-		}, this.#lingerMs);
-	}
-	/**
-	* Send any pending batch immediately and wait for all in-flight batches.
-	*
-	* Call this before shutdown to ensure all messages are delivered.
-	*/
-	async flush() {
-		if (this.#lingerTimeout) {
-			clearTimeout(this.#lingerTimeout);
-			this.#lingerTimeout = null;
-		}
-		if (this.#pendingBatch.length > 0) this.#enqueuePendingBatch();
-		await this.#queue.drained();
-	}
-	/**
-	* Flush pending messages and close the producer.
-	*
-	* After calling close(), further append() calls will throw.
-	*/
-	async close() {
-		if (this.#closed) return;
-		this.#closed = true;
-		try {
-			await this.flush();
-		} catch {}
-	}
-	/**
-	* Increment epoch and reset sequence.
-	*
-	* Call this when restarting the producer to establish a new session.
-	* Flushes any pending messages first.
-	*/
-	async restart() {
-		await this.flush();
-		this.#epoch++;
-		this.#nextSeq = 0;
-	}
-	/**
-	* Current epoch for this producer.
-	*/
-	get epoch() {
-		return this.#epoch;
-	}
-	/**
-	* Next sequence number to be assigned.
-	*/
-	get nextSeq() {
-		return this.#nextSeq;
-	}
-	/**
-	* Number of messages in the current pending batch.
-	*/
-	get pendingCount() {
-		return this.#pendingBatch.length;
-	}
-	/**
-	* Number of batches currently in flight.
-	*/
-	get inFlightCount() {
-		return this.#queue.length();
-	}
-	/**
-	* Enqueue the current pending batch for processing.
-	*/
-	#enqueuePendingBatch() {
-		if (this.#pendingBatch.length === 0) return;
-		const batch = this.#pendingBatch;
-		const seq = this.#nextSeq;
-		this.#pendingBatch = [];
-		this.#batchBytes = 0;
-		this.#nextSeq++;
-		if (this.#autoClaim && !this.#epochClaimed && this.#queue.length() > 0) this.#queue.drained().then(() => {
-			this.#queue.push({
-				batch,
-				seq
-			}).catch(() => {});
-		});
-		else this.#queue.push({
-			batch,
-			seq
-		}).catch(() => {});
-	}
-	/**
-	* Batch worker - processes batches via fastq.
-	*/
-	async #batchWorker(task) {
-		const { batch, seq } = task;
-		const epoch = this.#epoch;
-		try {
-			await this.#doSendBatch(batch, seq, epoch);
-			if (!this.#epochClaimed) this.#epochClaimed = true;
-			this.#signalSeqComplete(epoch, seq, void 0);
-		} catch (error) {
-			this.#signalSeqComplete(epoch, seq, error);
-			if (this.#onError) this.#onError(error);
-			throw error;
-		}
-	}
-	/**
-	* Signal that a sequence has completed (success or failure).
-	*/
-	#signalSeqComplete(epoch, seq, error) {
-		let epochMap = this.#seqState.get(epoch);
-		if (!epochMap) {
-			epochMap = new Map();
-			this.#seqState.set(epoch, epochMap);
-		}
-		const state = epochMap.get(seq);
-		if (state) {
-			state.resolved = true;
-			state.error = error;
-			for (const waiter of state.waiters) waiter(error);
-			state.waiters = [];
-		} else epochMap.set(seq, {
-			resolved: true,
-			error,
-			waiters: []
-		});
-		const cleanupThreshold = seq - this.#maxInFlight * 3;
-		if (cleanupThreshold > 0) {
-			for (const oldSeq of epochMap.keys()) if (oldSeq < cleanupThreshold) epochMap.delete(oldSeq);
-		}
-	}
-	/**
-	* Wait for a specific sequence to complete.
-	* Returns immediately if already completed.
-	* Throws if the sequence failed.
-	*/
-	#waitForSeq(epoch, seq) {
-		let epochMap = this.#seqState.get(epoch);
-		if (!epochMap) {
-			epochMap = new Map();
-			this.#seqState.set(epoch, epochMap);
-		}
-		const state = epochMap.get(seq);
-		if (state?.resolved) {
-			if (state.error) return Promise.reject(state.error);
-			return Promise.resolve();
-		}
-		return new Promise((resolve, reject) => {
-			const waiter = (err) => {
-				if (err) reject(err);
-				else resolve();
-			};
-			if (state) state.waiters.push(waiter);
-			else epochMap.set(seq, {
-				resolved: false,
-				waiters: [waiter]
-			});
-		});
-	}
-	/**
-	* Actually send the batch to the server.
-	* Handles auto-claim retry on 403 (stale epoch) if autoClaim is enabled.
-	* Does NOT implement general retry/backoff for network errors or 5xx responses.
-	*/
-	async #doSendBatch(batch, seq, epoch) {
-		const contentType = this.#stream.contentType ?? `application/octet-stream`;
-		const isJson = normalizeContentType(contentType) === `application/json`;
-		let batchedBody;
-		if (isJson) {
-			const values = batch.map((e) => e.data);
-			batchedBody = JSON.stringify(values);
-		} else {
-			const totalSize = batch.reduce((sum, e) => sum + e.body.length, 0);
-			const concatenated = new Uint8Array(totalSize);
-			let offset = 0;
-			for (const entry of batch) {
-				concatenated.set(entry.body, offset);
-				offset += entry.body.length;
-			}
-			batchedBody = concatenated;
-		}
-		const url = this.#stream.url;
-		const headers = {
-			"content-type": contentType,
-			[PRODUCER_ID_HEADER]: this.#producerId,
-			[PRODUCER_EPOCH_HEADER]: epoch.toString(),
-			[PRODUCER_SEQ_HEADER]: seq.toString()
-		};
-		const response = await this.#fetchClient(url, {
-			method: `POST`,
-			headers,
-			body: batchedBody,
-			signal: this.#signal
-		});
-		if (response.status === 204) return {
-			offset: ``,
-			duplicate: true
-		};
-		if (response.status === 200) {
-			const resultOffset = response.headers.get(STREAM_OFFSET_HEADER) ?? ``;
-			return {
-				offset: resultOffset,
-				duplicate: false
-			};
-		}
-		if (response.status === 403) {
-			const currentEpochStr = response.headers.get(PRODUCER_EPOCH_HEADER);
-			const currentEpoch = currentEpochStr ? parseInt(currentEpochStr, 10) : epoch;
-			if (this.#autoClaim) {
-				const newEpoch = currentEpoch + 1;
-				this.#epoch = newEpoch;
-				this.#nextSeq = 1;
-				return this.#doSendBatch(batch, 0, newEpoch);
-			}
-			throw new StaleEpochError(currentEpoch);
-		}
-		if (response.status === 409) {
-			const expectedSeqStr = response.headers.get(PRODUCER_EXPECTED_SEQ_HEADER);
-			const expectedSeq = expectedSeqStr ? parseInt(expectedSeqStr, 10) : 0;
-			if (expectedSeq < seq) {
-				const waitPromises = [];
-				for (let s = expectedSeq; s < seq; s++) waitPromises.push(this.#waitForSeq(epoch, s));
-				await Promise.all(waitPromises);
-				return this.#doSendBatch(batch, seq, epoch);
-			}
-			const receivedSeqStr = response.headers.get(PRODUCER_RECEIVED_SEQ_HEADER);
-			const receivedSeq = receivedSeqStr ? parseInt(receivedSeqStr, 10) : seq;
-			throw new SequenceGapError(expectedSeq, receivedSeq);
-		}
-		if (response.status === 400) {
-			const error$1 = await DurableStreamError.fromResponse(response, url);
-			throw error$1;
-		}
-		const error = await FetchError.fromResponse(response, url);
-		throw error;
-	}
-	/**
-	* Clear pending batch and report error.
-	*/
-	#rejectPendingBatch(error) {
-		if (this.#onError && this.#pendingBatch.length > 0) this.#onError(error);
-		this.#pendingBatch = [];
-		this.#batchBytes = 0;
-		if (this.#lingerTimeout) {
-			clearTimeout(this.#lingerTimeout);
-			this.#lingerTimeout = null;
-		}
-	}
-};
-
 //#endregion
 exports.BackoffDefaults = BackoffDefaults
 exports.CURSOR_QUERY_PARAM = CURSOR_QUERY_PARAM