@cntryl/fitz 0.0.3 → 0.0.4

package/dist/index.cjs

@@ -978,7 +978,7 @@ function createMultiplexer(observability = {}) {
 		const span = tracer?.startSpan("fitz.request", attributes);
 		let spanEnded = false;
 		if (signal?.aborted) {
-			const error = abortError$2();
+			const error = abortError$3();
 			span?.recordException(error);
 			span?.end();
 			meter?.counter("fitz.request.failed", 1, {
@@ -1052,7 +1052,7 @@ function createMultiplexer(observability = {}) {
 		heapifyUp(requestEntry.timeoutIndex);
 		if (signal) {
 			onAbort = () => {
-				failRequest(abortError$2());
+				failRequest(abortError$3());
 			};
 			signal.addEventListener("abort", onAbort, { once: true });
 		}
@@ -1072,7 +1072,7 @@ function createMultiplexer(observability = {}) {
 			return deferred.promise;
 		}, (err) => {
 			if (!finalize()) {
-				if (signal?.aborted) throw abortError$2();
+				if (signal?.aborted) throw abortError$3();
 				throw err;
 			}
 			unregisterRequest(messageType, requestEntry);
@@ -1085,7 +1085,7 @@ function createMultiplexer(observability = {}) {
 				span?.end();
 				spanEnded = true;
 			}
-			if (signal?.aborted) throw abortError$2();
+			if (signal?.aborted) throw abortError$3();
 			throw err;
 		});
 	};
@@ -1197,7 +1197,7 @@ function createMultiplexer(observability = {}) {
 const Multiplexer = function(observability = {}) {
 	return createMultiplexer(observability);
 };
-function abortError$2() {
+function abortError$3() {
 	const error = /* @__PURE__ */ new Error("The operation was aborted");
 	error.name = "AbortError";
 	return error;
@@ -1281,7 +1281,7 @@ function shouldRetryOperation(retryClass, error) {
 //#region src/client/connection.ts
 const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 const sleepWithAbort = async (ms, signal) => {
-	if (signal?.aborted) throw abortError$1();
+	if (signal?.aborted) throw abortError$2();
 	if (ms <= 0) return;
 	await new Promise((resolve, reject) => {
 		const timer = setTimeout(() => {
@@ -1290,7 +1290,7 @@ const sleepWithAbort = async (ms, signal) => {
 		}, ms);
 		const onAbort = () => {
 			cleanup();
-			reject(abortError$1());
+			reject(abortError$2());
 		};
 		const cleanup = () => {
 			clearTimeout(timer);
@@ -1366,7 +1366,7 @@ function createRequestGate(maxConcurrency, maxQueueSize) {
 	let closed = false;
 	const queue = [];
 	const acquire = async (signal) => {
-		if (signal?.aborted) throw abortError$1();
+		if (signal?.aborted) throw abortError$2();
 		if (closed) throw connectionClosedError();
 		return await new Promise((resolve, reject) => {
 			const grant = () => {
@@ -1389,7 +1389,7 @@ function createRequestGate(maxConcurrency, maxQueueSize) {
 			waiter.onAbort = () => {
 				removeWaiter(waiter);
 				cleanup();
-				reject(abortError$1());
+				reject(abortError$2());
 			};
 			if (signal) signal.addEventListener("abort", waiter.onAbort, { once: true });
 			if (activeCount < maxConcurrency) {
@@ -1438,7 +1438,7 @@ function createRequestGate(maxConcurrency, maxQueueSize) {
 		close
 	};
 }
-function abortError$1() {
+function abortError$2() {
 	const error = /* @__PURE__ */ new Error("The operation was aborted");
 	error.name = "AbortError";
 	return error;
@@ -1447,14 +1447,14 @@ function connectionClosedError() {
 	return new ConnectionError("Connection closed", { state: "CLOSED" });
 }
 function throwIfAborted$1(signal) {
-	if (signal?.aborted) throw abortError$1();
+	if (signal?.aborted) throw abortError$2();
 }
 function isAbortError$1(error) {
 	return error instanceof Error && error.name === "AbortError";
 }
 const waitForSharedPromise$1 = async (promise, signal) => {
 	if (!signal) return promise;
-	if (signal.aborted) throw abortError$1();
+	if (signal.aborted) throw abortError$2();
 	return await new Promise((resolve, reject) => {
 		let settled = false;
 		const cleanup = () => {
@@ -1467,7 +1467,7 @@ const waitForSharedPromise$1 = async (promise, signal) => {
 			callback();
 		};
 		const onAbort = () => {
-			settle(() => reject(abortError$1()));
+			settle(() => reject(abortError$2()));
 		};
 		signal.addEventListener("abort", onAbort, { once: true });
 		promise.then((value) => {
@@ -1488,6 +1488,9 @@ function createConnection(transportFactory, tokenProvider, options = {}) {
 	const retryMaxAttempts = options.retry?.maxAttempts ?? 3;
 	const retryBackoffMs = options.retry?.backoffMs ?? 100;
 	const retryMaxBackoffMs = options.retry?.maxBackoffMs ?? 1e3;
+	const heartbeatEnabled = options.heartbeat?.enabled ?? true;
+	const heartbeatIntervalMs = options.heartbeat?.intervalMs ?? 1e4;
+	const heartbeatTimeoutMs = options.heartbeat?.timeoutMs ?? 3e4;
 	const maxInFlightRequests = options.maxInFlightRequests ?? 256;
 	const maxRequestQueueSize = options.maxRequestQueueSize ?? 1024;
 	const observability = options.observability;
@@ -1504,6 +1507,7 @@ function createConnection(transportFactory, tokenProvider, options = {}) {
 	let permanentlyClosed = false;
 	let connectPromise = null;
 	let reconnectPromise = null;
+	let connectionLossPromise = null;
 	let reconnectRestoreActive = false;
 	let authOutcome = null;
 	let authRejected = false;
@@ -1513,6 +1517,10 @@ function createConnection(transportFactory, tokenProvider, options = {}) {
 	const closeAbortController = new AbortController();
 	const connectionScope = createScope("connection");
 	const readyListeners = /* @__PURE__ */ new Set();
+	let heartbeatTimer = null;
+	let heartbeatTransport = null;
+	let heartbeatPending = false;
+	let lastActivityAt = Date.now();
 	const log = (level, event, fields) => {
 		observability?.logger?.log(level, event, fields);
 	};
@@ -1582,6 +1590,7 @@ function createConnection(transportFactory, tokenProvider, options = {}) {
 		permanentlyClosed = true;
 		closeRequested = true;
 		receiveLoopAbort = true;
+		stopHeartbeat();
 		closeAbortController.abort();
 		asyncHandlerDispatcher.close();
 		const scopeDisposePromise = connectionScope.dispose();
@@ -1763,7 +1772,7 @@ function createConnection(transportFactory, tokenProvider, options = {}) {
 				cb();
 			};
 			const onAbort = () => {
-				settle(() => reject(abortError$1()));
+				settle(() => reject(abortError$2()));
 			};
 			const onStateChange = () => {
 				const failure = readyFailure();
@@ -1846,6 +1855,75 @@ function createConnection(transportFactory, tokenProvider, options = {}) {
 			}
 		}
 	};
+	const withWriteLock = async (operation) => {
+		const prior = writeChain;
+		let release;
+		writeChain = new Promise((resolve) => {
+			release = resolve;
+		});
+		await prior;
+		try {
+			return await operation();
+		} finally {
+			release();
+		}
+	};
+	const markOutboundActivity = () => {
+		lastActivityAt = Date.now();
+	};
+	const markRemoteActivity = () => {
+		lastActivityAt = Date.now();
+	};
+	const stopHeartbeat = () => {
+		if (heartbeatTimer) {
+			clearTimeout(heartbeatTimer);
+			heartbeatTimer = null;
+		}
+		heartbeatTransport = null;
+		heartbeatPending = false;
+	};
+	const startHeartbeat = (activeTransport) => {
+		if (!heartbeatEnabled) return;
+		stopHeartbeat();
+		activeTransport.enableKeepAlive?.(heartbeatIntervalMs);
+		heartbeatTransport = activeTransport;
+		markRemoteActivity();
+		const scheduleNext = () => {
+			if (closeRequested || receiveLoopAbort || heartbeatTransport !== activeTransport) return;
+			heartbeatTimer = setTimeout(tick, heartbeatIntervalMs);
+		};
+		const tick = () => {
+			heartbeatTimer = null;
+			if (closeRequested || receiveLoopAbort || heartbeatTransport !== activeTransport) return;
+			const now = Date.now();
+			if (now - lastActivityAt < heartbeatIntervalMs) {
+				scheduleNext();
+				return;
+			}
+			const supportsHeartbeat = activeTransport.supportsHeartbeat?.() ?? true;
+			if (!heartbeatPending && supportsHeartbeat && activeTransport.sendHeartbeat) {
+				heartbeatPending = true;
+				const heartbeatSentAt = now;
+				const dispatchHeartbeat = (heartbeat) => activeTransport.sendHeartbeat(heartbeat);
+				withWriteLock(async () => {
+					await dispatchHeartbeat({ timeoutMs: heartbeatTimeoutMs });
+				}).then(() => {
+					if (heartbeatTransport !== activeTransport) return;
+					heartbeatPending = false;
+					markRemoteActivity();
+				}).catch((error) => {
+					if (heartbeatTransport !== activeTransport) return;
+					heartbeatPending = false;
+					if (lastActivityAt > heartbeatSentAt) return;
+					const heartbeatError = new TransportError(`Heartbeat failed: ${describeError(error)}`);
+					activeTransport.close().catch(() => void 0);
+					handleConnectionLoss(heartbeatError);
+				});
+			}
+			scheduleNext();
+		};
+		scheduleNext();
+	};
 	const openAndAuthenticate = async (isReconnect, signal) => {
 		throwIfAborted$1(signal);
 		receiveLoopAbort = false;
@@ -1853,10 +1931,13 @@ function createConnection(transportFactory, tokenProvider, options = {}) {
 		requestGate = createRequestGate(maxInFlightRequests, maxRequestQueueSize);
 		const activeTransport = transportFactory();
 		transport = activeTransport;
+		stopHeartbeat();
 		setState(isReconnect ? "RECONNECTING" : "CONNECTING");
 		emitLifecycleEvent(isReconnect ? "reconnect_start" : "connect_start");
 		await activeTransport.connect();
+		markRemoteActivity();
 		if (closeRequested) {
+			stopHeartbeat();
 			await activeTransport.close().catch(() => void 0);
 			if (transport === activeTransport) transport = null;
 			throw connectionClosedError();
@@ -1889,6 +1970,7 @@ function createConnection(transportFactory, tokenProvider, options = {}) {
 			hasEstablishedSession = true;
 			reconnectExhausted = false;
 			setState("AUTHENTICATED");
+			startHeartbeat(activeTransport);
 			if (!isReconnect) multiplexer.setConnected();
 			emitLifecycleEvent(isReconnect ? "reconnect_succeeded" : "connect_succeeded");
 		} catch (error) {
@@ -1896,6 +1978,7 @@ function createConnection(transportFactory, tokenProvider, options = {}) {
 			reconnectRestoreActive = false;
 			multiplexer.setDisconnected();
 			emitDisconnect();
+			stopHeartbeat();
 			if (activeTransport) await activeTransport.close().catch(() => void 0);
 			if (transport === activeTransport) transport = null;
 			const rejectedAuth = error instanceof AuthenticationError;
@@ -1903,7 +1986,7 @@ function createConnection(transportFactory, tokenProvider, options = {}) {
 			if (closeRequested) setState("CLOSED");
 			else setState(rejectedAuth ? "CLOSED" : "DISCONNECTED");
 			emitLifecycleEvent(isReconnect ? "reconnect_failed" : "connect_failed", error);
-			if (isAbortError$1(error)) throw abortError$1();
+			if (isAbortError$1(error)) throw abortError$2();
 			throw error;
 		}
 	};
@@ -1911,10 +1994,12 @@ function createConnection(transportFactory, tokenProvider, options = {}) {
 		const token = await tokenProvider();
 		const frame = FrameCodec.encodeFrame(1, utf8Encoder.encode(token));
 		await ensureTransport().send(frame);
+		markOutboundActivity();
 	};
 	const startReceiveLoop = async () => {
 		while (!receiveLoopAbort && !closeRequested) try {
 			const data = await ensureTransport().receive();
+			markRemoteActivity();
 			const frames = frameParser.parseFrames(data);
 			for (const frame of frames) multiplexer.dispatch(frame.messageType, frame.payload);
 		} catch (error) {
@@ -1924,6 +2009,17 @@ function createConnection(transportFactory, tokenProvider, options = {}) {
 		}
 	};
 	const handleConnectionLoss = async (error) => {
+		if (connectionLossPromise) {
+			await connectionLossPromise;
+			return;
+		}
+		connectionLossPromise = handleConnectionLossOnce(error).finally(() => {
+			connectionLossPromise = null;
+		});
+		await connectionLossPromise;
+	};
+	const handleConnectionLossOnce = async (error) => {
+		stopHeartbeat();
 		multiplexer.setDisconnected();
 		requestGate.close();
 		emitDisconnect();
@@ -2010,17 +2106,10 @@ function createConnection(transportFactory, tokenProvider, options = {}) {
 		notifyReadyListeners();
 	};
 	const sendSerialized = async (transport, data) => {
-		const prior = writeChain;
-		let release;
-		writeChain = new Promise((resolve) => {
-			release = resolve;
-		});
-		await prior;
-		try {
+		await withWriteLock(async () => {
 			await transport.send(data);
-		} finally {
-			release();
-		}
+			markOutboundActivity();
+		});
 	};
 	const emitLifecycleEvent = (event, error, attempt) => {
 		const payload = {
@@ -2096,6 +2185,7 @@ function createWebSocketTransport(url, options = {}) {
 	let receiverResolve = null;
 	const timeout = options.timeout ?? 3e4;
 	const maxFrameSize = options.maxFrameSize ?? 65535;
+	const receiveTimeoutEnabled = options.receiveTimeout ?? true;
 	const enqueueMessage = (data) => {
 		if (receiverResolve) {
 			receiverResolve(data);
@@ -2169,6 +2259,56 @@ function createWebSocketTransport(url, options = {}) {
 			}
 		});
 	};
+	const sendHeartbeat = async (heartbeatOptions) => {
+		if (!connected || !ws) throw new TransportError("WebSocket is not connected");
+		const activeWs = ws;
+		if (typeof activeWs.ping !== "function" || typeof activeWs.once !== "function" || typeof activeWs.removeListener !== "function") throw new TransportError("WebSocket heartbeat is not supported");
+		const socket = activeWs;
+		return new Promise((resolve, reject) => {
+			let settled = false;
+			let timeoutId = null;
+			const cleanup = () => {
+				if (timeoutId) clearTimeout(timeoutId);
+				socket.removeListener("pong", onPong);
+				socket.removeListener("close", onClose);
+				socket.removeListener("error", onError);
+			};
+			const settle = (callback) => {
+				if (settled) return;
+				settled = true;
+				cleanup();
+				callback();
+			};
+			const onPong = () => {
+				settle(resolve);
+			};
+			const onClose = () => {
+				settle(() => reject(new TransportError("WebSocket closed during heartbeat")));
+			};
+			const onError = (...args) => {
+				const event = args[0];
+				const message = event instanceof Error ? event.message : event?.message || "unknown error";
+				settle(() => reject(new TransportError(`WebSocket heartbeat failed: ${message}`)));
+			};
+			timeoutId = setTimeout(() => {
+				settle(() => reject(new TimeoutError(`WebSocket heartbeat timeout after ${heartbeatOptions.timeoutMs}ms`)));
+			}, heartbeatOptions.timeoutMs);
+			socket.once("pong", onPong);
+			socket.once("close", onClose);
+			socket.once("error", onError);
+			try {
+				socket.ping(new Uint8Array(), void 0, (err) => {
+					if (err) settle(() => reject(new TransportError(`WebSocket ping failed: ${err.message}`)));
+				});
+			} catch (err) {
+				settle(() => reject(new TransportError(`WebSocket heartbeat error: ${err instanceof Error ? err.message : String(err)}`)));
+			}
+		});
+	};
+	const supportsHeartbeat = () => {
+		return typeof ws?.ping === "function" && typeof ws?.once === "function" && typeof ws?.removeListener === "function";
+	};
+	const enableKeepAlive = () => void 0;
 	const receive = async () => {
 		if (receiveQueue.length > 0) {
 			const message = receiveQueue.shift();
@@ -2177,12 +2317,12 @@ function createWebSocketTransport(url, options = {}) {
 		}
 		if (!connected) throw new TransportError("Connection closed");
 		return new Promise((resolve, reject) => {
-			const timeoutId = setTimeout(() => {
+			const timeoutId = receiveTimeoutEnabled ? setTimeout(() => {
 				receiverResolve = null;
 				reject(new TimeoutError(`WebSocket receive timeout after ${timeout}ms`));
-			}, timeout);
+			}, timeout) : null;
 			receiverResolve = (data) => {
-				clearTimeout(timeoutId);
+				if (timeoutId) clearTimeout(timeoutId);
 				receiverResolve = null;
 				if (data === null) {
 					reject(new TransportError("Connection closed"));
@@ -2217,6 +2357,9 @@ function createWebSocketTransport(url, options = {}) {
 		connect,
 		send,
 		receive,
+		sendHeartbeat,
+		supportsHeartbeat,
+		enableKeepAlive,
 		close,
 		getUrl,
 		isConnected
@@ -2242,6 +2385,7 @@ function createTcpTransport(url, options = {}) {
 	let receiverResolve = null;
 	const timeout = options.timeout ?? 3e4;
 	const maxFrameSize = options.maxFrameSize ?? 65535;
+	const receiveTimeoutEnabled = options.receiveTimeout ?? true;
 	let lengthBuffer = new Uint8Array(4);
 	let lengthOffset = 0;
 	let currentMessageLength = null;
@@ -2316,7 +2460,7 @@ function createTcpTransport(url, options = {}) {
 					clearTimeout(connectTimeout);
 					connected = true;
 					activeSocket.setNoDelay(true);
-					activeSocket.setTimeout(timeout);
+					activeSocket.setTimeout(receiveTimeoutEnabled ? timeout : 0);
 					resolve();
 				});
 				activeSocket.on("data", (chunk) => {
@@ -2334,8 +2478,10 @@ function createTcpTransport(url, options = {}) {
 					if (receiverResolve) receiverResolve(new Uint8Array(0));
 				});
 				activeSocket.on("timeout", () => {
-					activeSocket.destroy();
-					connected = false;
+					if (receiveTimeoutEnabled) {
+						activeSocket.destroy();
+						connected = false;
+					}
 				});
 			} catch (err) {
 				reject(new TransportError(`Failed to create TCP socket: ${err instanceof Error ? err.message : String(err)}`));
@@ -2360,6 +2506,10 @@ function createTcpTransport(url, options = {}) {
 			});
 		});
 	};
+	const enableKeepAlive = (intervalMs) => {
+		socket?.setKeepAlive(true, intervalMs);
+	};
+	const supportsHeartbeat = () => false;
 	const receive = async () => {
 		if (receiveQueue.length > 0) {
 			const message = receiveQueue.shift();
@@ -2367,12 +2517,12 @@ function createTcpTransport(url, options = {}) {
 			return message;
 		}
 		return new Promise((resolve, reject) => {
-			const timeoutId = setTimeout(() => {
+			const timeoutId = receiveTimeoutEnabled ? setTimeout(() => {
 				receiverResolve = null;
 				reject(new TimeoutError(`TCP receive timeout after ${timeout}ms`));
-			}, timeout);
+			}, timeout) : null;
 			receiverResolve = (data) => {
-				clearTimeout(timeoutId);
+				if (timeoutId) clearTimeout(timeoutId);
 				receiverResolve = null;
 				if (data.length === 0) reject(new TransportError("Connection closed"));
 				else resolve(data);
@@ -2404,6 +2554,8 @@ function createTcpTransport(url, options = {}) {
 		connect,
 		send,
 		receive,
+		supportsHeartbeat,
+		enableKeepAlive,
 		close,
 		getUrl,
 		isConnected
@@ -2782,6 +2934,64 @@ const KvClient = function(connection) {
 	return createKvClient(connection);
 };
 //#endregion
+//#region src/core/wake-gate.ts
+function abortError$1() {
+	const error = /* @__PURE__ */ new Error("The operation was aborted");
+	error.name = "AbortError";
+	return error;
+}
+function createWakeGate() {
+	let currentVersion = 0;
+	const waiters = /* @__PURE__ */ new Set();
+	const cleanup = (waiter) => {
+		waiters.delete(waiter);
+		if (waiter.signal && waiter.onAbort) waiter.signal.removeEventListener("abort", waiter.onAbort);
+	};
+	const wake = () => {
+		currentVersion += 1;
+		const version = currentVersion;
+		for (const waiter of Array.from(waiters)) {
+			cleanup(waiter);
+			waiter.resolve(version);
+		}
+		return version;
+	};
+	const waitAfter = async (observedVersion, options = {}) => {
+		if (currentVersion > observedVersion) return currentVersion;
+		if (options.signal?.aborted) throw abortError$1();
+		return await new Promise((resolve, reject) => {
+			const waiter = {
+				observedVersion,
+				resolve,
+				reject,
+				signal: options.signal
+			};
+			waiter.onAbort = () => {
+				cleanup(waiter);
+				reject(abortError$1());
+			};
+			if (options.signal) options.signal.addEventListener("abort", waiter.onAbort, { once: true });
+			if (currentVersion > observedVersion) {
+				cleanup(waiter);
+				resolve(currentVersion);
+				return;
+			}
+			waiters.add(waiter);
+		});
+	};
+	const wait = async (options) => {
+		return await waitAfter(currentVersion, options);
+	};
+	return {
+		get version() {
+			return currentVersion;
+		},
+		wake,
+		waitAfter,
+		wait
+	};
+}
+//#endregion
 //#region src/domains/queue/codec.ts
 /**
 * Queue domain codec for encoding and decoding protocol messages.
@@ -3120,43 +3330,55 @@ function createQueueClient(connection) {
 		let items = await reserveOnce(route, leaseSeconds, batchSize);
 		if (items.length > 0) return items;
 		const deadline = Date.now() + waitSeconds * 1e3;
-		let pendingNotifications = 0;
-		let waiter;
-		const subscription = await subscribe(route, async () => {
-			pendingNotifications += 1;
-			if (!waiter) return;
-			const resolve = waiter;
-			waiter = void 0;
-			pendingNotifications = 0;
-			resolve();
+		const wakeGate = createWakeGate();
+		const subscription = await subscribe(route, () => {
+			wakeGate.wake();
 		});
 		try {
 			while (true) {
+				const observed = wakeGate.version;
 				items = await reserveOnce(route, leaseSeconds, batchSize);
 				if (items.length > 0) return items;
 				const remainingMs = deadline - Date.now();
 				if (remainingMs <= 0) return items;
-				await new Promise((resolve) => {
-					if (pendingNotifications > 0) {
-						pendingNotifications = 0;
-						resolve();
-						return;
-					}
-					const release = () => {
-						clearTimeout(timeoutId);
-						if (waiter === release) waiter = void 0;
-						resolve();
-					};
-					const timeoutId = setTimeout(release, remainingMs);
-					waiter = release;
+				const waitPromise = wakeGate.waitAfter(observed);
+				let timeoutId = null;
+				const timeoutPromise = new Promise((resolve) => {
+					timeoutId = setTimeout(() => {
+						resolve("timeout");
+					}, remainingMs);
 				});
+				if (await Promise.race([waitPromise.then(() => {
+					if (timeoutId) clearTimeout(timeoutId);
+					return "wake";
+				}), timeoutPromise]) === "timeout") return items;
 			}
 		} finally {
-			await subscription.unsubscribe();
+			await subscription.unsubscribe().catch(() => void 0);
 		}
 	};
-	const reserveOnce = async (route, leaseSeconds, batchSize) => {
-		const response = await requestFrame(202, QueueCodec.encodeReserve(route, leaseSeconds, batchSize));
+	const reserveWhenAvailable = async function* (route, options) {
+		assertQueueReserveRoute(route);
+		const wakeGate = createWakeGate();
+		const subscription = await subscribe(route, () => {
+			wakeGate.wake();
+		});
+		try {
+			while (true) {
+				const observed = wakeGate.version;
+				const items = await reserveOnce(route, options.leaseSeconds, options.batchSize ?? 1, options.signal);
+				if (items.length > 0) {
+					yield items;
+					continue;
+				}
+				await wakeGate.waitAfter(observed, { signal: options.signal });
+			}
+		} finally {
+			await subscription.unsubscribe().catch(() => void 0);
+		}
+	};
+	const reserveOnce = async (route, leaseSeconds, batchSize, signal) => {
+		const response = await requestFrame(202, QueueCodec.encodeReserve(route, leaseSeconds, batchSize), signal);
 		const decoded = QueueCodec.decodeReserveResponse(response);
 		checkStatus(decoded, "RESERVE");
 		return (decoded.items ?? []).map((item) => createQueueItem(item.id, item.token, item.body, route, connection));
@@ -3245,6 +3467,7 @@ function createQueueClient(connection) {
 	return {
 		enqueue,
 		reserve,
+		reserveWhenAvailable,
 		subscribe
 	};
 }
@@ -4963,6 +5186,33 @@ function createStreamClient(connection) {
 		const page = await readPage(route, startOffset, limit, options);
 		return StreamCodec.flattenStreamReadItems(page.items);
 	};
+	const readWhenCommitted = async function* (route, options) {
+		assertStreamPattern(route);
+		const wakeGate = createWakeGate();
+		const subscription = await subscribe(route, () => {
+			wakeGate.wake();
+		});
+		try {
+			let offset = options.offset;
+			while (true) {
+				const observed = wakeGate.version;
+				const page = await readPage(route, offset, options.batchSize ?? 100, {
+					maxBytes: options.maxBytes,
+					filter: options.filter,
+					signal: options.signal
+				});
+				if (page.items.length > 0) {
+					offset = page.cursor.lastResourceOffset + 1n;
+					const records = StreamCodec.flattenStreamReadItems(page.items);
+					if (records.length > 0) yield records;
+				}
+				if (page.cursor.hasMore) continue;
+				await wakeGate.waitAfter(observed, { signal: options.signal });
+			}
+		} finally {
+			await subscription.unsubscribe().catch(() => void 0);
+		}
+	};
 	const consume = async (route, startOffset, limit = 100, options) => {
 		return createAsyncIterableIterator(createSliceIterator(await read(route, startOffset, limit, options)));
 	};
@@ -5082,6 +5332,7 @@ function createStreamClient(connection) {
 		begin,
 		readPage,
 		read,
+		readWhenCommitted,
 		consume,
 		peek,
 		metadata,
@@ -5262,6 +5513,7 @@ function createScheduleClient(connection) {
 	const { requestFrame, requestReconnectFrame } = createDomainClient(connection);
 	const subscriptionsByPattern = /* @__PURE__ */ new Map();
 	const patternsBySubId = /* @__PURE__ */ new Map();
+	const pendingNotificationsBySubId = /* @__PURE__ */ new Map();
 	let notifyHandlerInitialized = false;
 	let nextHandlerId = 1;
 	connection.onReconnect(async () => {
@@ -5272,6 +5524,7 @@ function createScheduleClient(connection) {
 		}));
 		subscriptionsByPattern.clear();
 		patternsBySubId.clear();
+		pendingNotificationsBySubId.clear();
 		for (const subscription of subscriptions) {
 			const subId = await subscribeWire(subscription.pattern, requestReconnectFrame);
 			subscriptionsByPattern.set(subscription.pattern, {
@@ -5296,6 +5549,29 @@ function createScheduleClient(connection) {
 		const decoded = ScheduleCodec.decodeListResponse(assertSuccess(response, "LIST"));
 		return [decoded.entries, decoded.totalCount];
 	};
+	const waitForNotifications = async function* (route, options = {}) {
+		assertConcreteScheduleRoute(route);
+		const wakeGate = createWakeGate();
+		const pendingNotifications = [];
+		const subscription = await subscribe(route, (notification) => {
+			pendingNotifications.push(notification);
+			wakeGate.wake();
+		});
+		try {
+			while (true) {
+				const notification = pendingNotifications.shift();
+				if (notification) {
+					yield notification;
+					continue;
+				}
+				const observed = wakeGate.version;
+				if (pendingNotifications.length > 0) continue;
+				await wakeGate.waitAfter(observed, { signal: options.signal });
+			}
+		} finally {
+			await subscription.unsubscribe().catch(() => void 0);
+		}
+	};
 	const subscribe = async (pattern, handler) => {
 		assertConcreteScheduleRoute(pattern);
 		initNotifyHandler();
@@ -5319,6 +5595,7 @@ function createScheduleClient(connection) {
 			patternsBySubId.set(subId, pattern);
 		}
 		subscription.handlers.set(handlerId, handler);
+		flushPendingNotifications(subId);
 		return createScheduleSubscription(subId, pattern, async () => {
 			await unsubscribe(pattern, handlerId);
 		});
@@ -5330,6 +5607,7 @@ function createScheduleClient(connection) {
 		if (subscription.handlers.size > 0) return;
 		subscriptionsByPattern.delete(pattern);
 		patternsBySubId.delete(subscription.subId);
+		pendingNotificationsBySubId.delete(subscription.subId);
 		const response = await requestFrame(704, ScheduleCodec.encodeUnsubscribe(pattern));
 		ScheduleCodec.decodeUnsubscribeResponse(assertSuccess(response, "UNSUBSCRIBE"));
 	};
@@ -5340,16 +5618,40 @@ function createScheduleClient(connection) {
 			try {
 				const decoded = ScheduleCodec.decodeNotification(payload);
 				const pattern = patternsBySubId.get(decoded.subId);
-				if (!pattern) return;
+				if (!pattern) {
+					queuePendingNotification(decoded.subId, { payload: decoded.payload });
+					return;
+				}
 				const subscription = subscriptionsByPattern.get(pattern);
-				if (!subscription) return;
-				const notification = { payload: decoded.payload };
-				for (const handler of subscription.handlers.values()) connection.dispatchAsyncHandler(async () => {
-					await handler(notification);
-				});
+				if (!subscription) {
+					queuePendingNotification(decoded.subId, { payload: decoded.payload });
+					return;
+				}
+				dispatchNotification(subscription, { payload: decoded.payload });
 			} catch {}
 		});
 	};
+	const queuePendingNotification = (subId, notification) => {
+		const existing = pendingNotificationsBySubId.get(subId);
+		if (existing) {
+			existing.push(notification);
+			return;
+		}
+		pendingNotificationsBySubId.set(subId, [notification]);
+	};
+	const flushPendingNotifications = (subId) => {
+		const pending = pendingNotificationsBySubId.get(subId);
+		if (!pending || pending.length === 0) return;
+		pendingNotificationsBySubId.delete(subId);
+		const subscription = Array.from(subscriptionsByPattern.values()).find((entry) => entry.subId === subId);
+		if (!subscription) return;
+		for (const notification of pending) dispatchNotification(subscription, notification);
+	};
+	const dispatchNotification = (subscription, notification) => {
+		for (const handler of subscription.handlers.values()) connection.dispatchAsyncHandler(async () => {
+			await handler(notification);
+		});
+	};
 	const assertSuccess = (payload, operation) => {
 		const result = parseStandardResponse(payload);
 		if (result.success) return result.data;
@@ -5366,7 +5668,8 @@ function createScheduleClient(connection) {
 		create,
 		cancel,
 		list,
-		subscribe
+		subscribe,
+		waitForNotifications
 	};
 }
 const ScheduleClient = function(connection) {
@@ -5434,6 +5737,12 @@ function createClient(config) {
 			maxBackoffMs: 1e3,
 			...config.retry
 		},
+		heartbeat: {
+			enabled: true,
+			intervalMs: 1e4,
+			timeoutMs: 3e4,
+			...config.heartbeat
+		},
 		asyncHandlers: {
 			maxConcurrency: Infinity,
 			timeoutMs: 3e4,
@@ -5465,7 +5774,8 @@ function createClient(config) {
 		if (connection) return connection;
 		connection = createConnection(() => createTransport(resolvedConfig.url, resolvedConfig.transport, {
 			timeout: resolvedConfig.timeout,
-			maxFrameSize: resolvedConfig.maxFrameSize
+			maxFrameSize: resolvedConfig.maxFrameSize,
+			receiveTimeout: resolvedConfig.heartbeat?.enabled === false
 		}), resolveTokenProvider(), {
 			timeout: resolvedConfig.timeout,
 			authSettleDelayMs: resolvedConfig.authSettleDelayMs,
@@ -5473,6 +5783,7 @@ function createClient(config) {
 			maxRequestQueueSize: resolvedConfig.maxRequestQueueSize,
 			reconnect: resolvedConfig.reconnect,
 			retry: resolvedConfig.retry,
+			heartbeat: resolvedConfig.heartbeat,
 			observability,
 			asyncHandlers: resolvedConfig.asyncHandlers
 		});
@@ -5794,6 +6105,7 @@ exports.TimeoutError = TimeoutError;
 exports.TransportError = TransportError;
 exports.createClient = createClient;
 exports.createTaskGroup = createTaskGroup;
+exports.createWakeGate = createWakeGate;
 exports.isRetryable = isRetryable;
 
 //# sourceMappingURL=index.cjs.map