@deepseek-ai/dsh-timeout 0.2.1-alpha.1 → 0.2.1-alpha.3

package/README.i18n.yaml

@@ -45,8 +45,8 @@
   en: ceea0b46e6b8e15f
   zh: de87dccf08764061
 /deepseek-ai-dsh-timeout/understand-the-implementation/why-an-idle-watchdog-rearms:
-  en: 7200cfa587c53a9c
-  zh: 09d6b67dc1a31c5e
+  en: f7cd0e8ba2937f0f
+  zh: d17d546c5587b04e
 /deepseek-ai-dsh-timeout/further-exploration:
   en: 4c29a947e28047ad
   zh: d80f5ecb50b16203

package/README.md

@@ -103,7 +103,7 @@ The library is built on one boundary: share the timing and classification, keep
 
 ### Why an idle watchdog rearms
 
-`idleWatchdog` keeps one stable fused signal and arms the timer only while `next()` is outstanding; resolution disarms, later demand or `pulse()` rearms, disposal clears, and concurrent demand rejects. Only the transport observes the signal, so the provider's real read must listen to it — the DeepSeek and pi-ai adapters close their response body or SDK request on abort.
+`idleWatchdog` keeps one stable fused signal and arms the timer only while `next()` is outstanding; resolution disarms, later demand or `pulse()` rearms, disposal clears, and concurrent demand rejects. Unlike `deadline()`, an idle watchdog settles its outstanding demand on its own deadline: a read the transport leaves pending after an abort rejects `next()` with the watchdog's `TimeoutReason`, so a transport that never observes the signal cannot extend the wait past the idle interval. The signal still tells the transport to release its own resources — the DeepSeek and pi-ai adapters close their response body or SDK request on abort.
 
 </details>
 

package/README.zh.md

@@ -103,7 +103,7 @@ timer 只在某个迭代器 `next()` 尚未完成时启动，并会因不产生
 
 ### 空闲 watchdog 为何重新启动
 
-`idleWatchdog` 保持一个稳定的融合信号，只在 `next()` 尚未完成时启动 timer；完成后停止，后续需求或 `pulse()` 重新启动，dispose（资源释放）时清除，并发需求被拒绝。只有传输层观察该信号，因此提供方的真实读取必须监听它——DeepSeek 与 pi-ai 适配器会在中止时关闭响应正文或 SDK 请求。
+`idleWatchdog` 保持一个稳定的融合信号，只在 `next()` 尚未完成时启动 timer；完成后停止，后续需求或 `pulse()` 重新启动，dispose（资源释放）时清除，并发需求被拒绝。与 `deadline()` 不同，空闲 watchdog 会按自己的截止时间结算尚未完成的 demand：传输层在 abort 之后仍挂起的读取会让 `next()` 以该 watchdog 的 `TimeoutReason` reject，因此完全不观察信号的传输层也无法把等待拖过空闲间隔。信号仍用于让传输层释放自身资源——DeepSeek 与 pi-ai 适配器会在中止时关闭响应正文或 SDK 请求。
 
 </details>
 

package/lib/index.js

@@ -75,7 +75,8 @@ function deadline(upstream, timeoutMs, code) {
 * Create a rearmable idle watchdog for an async iterator. The timer exists only
 * while {@link IdleWatchdog.next} is outstanding, so consumer think time does
 * not count as provider idle time. The returned signal is stable for the whole
-* call and only notifies; the iterator must observe it to terminate its work.
+* call and only notifies; the iterator must observe it to release the resources
+* of a demand the deadline abandoned.
 *
 * @param upstream - caller cancellation fused into the stable signal.
 * @param timeoutMs - positive finite idle interval in milliseconds.
@@ -86,13 +87,14 @@ function idleWatchdog(upstream, timeoutMs, code) {
 	assertTimerDelay(timeoutMs, "idleWatchdog timeoutMs");
 	const timeout = new AbortController();
 	const signal = upstream === void 0 ? timeout.signal : AbortSignal.any([upstream, timeout.signal]);
+	const reason = new TimeoutReason(code, timeoutMs);
 	let timer;
 	let outstanding = false;
 	let disposed = false;
 	const arm = () => {
 		if (timer !== void 0) clearTimeout(timer);
 		timer = setTimeout(() => {
-			timeout.abort(new TimeoutReason(code, timeoutMs));
+			timeout.abort(reason);
 		}, timeoutMs);
 	};
 	return {
@@ -102,8 +104,15 @@ function idleWatchdog(upstream, timeoutMs, code) {
 			if (outstanding) throw new Error("idleWatchdog next is already outstanding");
 			outstanding = true;
 			arm();
+			const expired = Promise.withResolvers();
+			const onAbort = () => {
+				expired.reject(reason);
+			};
+			timeout.signal.addEventListener("abort", onAbort, { once: true });
 			try {
-				return await iterator.next();
+				return await Promise.race([iterator.next().finally(() => {
+					timeout.signal.removeEventListener("abort", onAbort);
+				}), expired.promise]);
 			} finally {
 				clearTimeout(timer);
 				timer = void 0;

package/lib/types/index.d.ts

@@ -45,9 +45,17 @@ export interface IdleWatchdog {
     /** Stable signal aborted by upstream cancellation or this watchdog's timeout. */
     readonly signal: AbortSignal;
     /**
-     * Await one iterator demand while the idle timer is armed.
+     * Await one iterator demand while the idle timer is armed. The deadline
+     * settles the demand even when the awaited work ignores its abort signal.
      * @param iterator - iterator whose next value represents provider progress.
      * @returns the iterator's next result.
+     * @throws The {@link TimeoutReason} of this watchdog when the idle interval
+     *   elapses first. Only that deadline settles the demand: an upstream
+     *   cancellation reaches the iterator through {@link IdleWatchdog.signal} and
+     *   never shortens the wait. The abandoned demand stays the caller's to release
+     *   through that signal; an async generator queues its own return behind it, so
+     *   callers must not await it. Disposal clears the timer without settling an
+     *   outstanding demand.
      */
     next<T>(iterator: AsyncIterator<T>): Promise<IteratorResult<T>>;
     /** Rearm an outstanding demand after transport activity that yields no iterator value; otherwise a no-op. */
@@ -70,7 +78,8 @@ export declare function deadline(upstream: AbortSignal | undefined, timeoutMs: n
  * Create a rearmable idle watchdog for an async iterator. The timer exists only
  * while {@link IdleWatchdog.next} is outstanding, so consumer think time does
  * not count as provider idle time. The returned signal is stable for the whole
- * call and only notifies; the iterator must observe it to terminate its work.
+ * call and only notifies; the iterator must observe it to release the resources
+ * of a demand the deadline abandoned.
  *
  * @param upstream - caller cancellation fused into the stable signal.
  * @param timeoutMs - positive finite idle interval in milliseconds.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-timeout",
   "description": "Zero-dependency timeout/deadline primitive: clampTimeout, deadline, timeoutOf, TimeoutReason (timing + classification only, no termination)",
-  "version": "0.2.1-alpha.1",
+  "version": "0.2.1-alpha.3",
   "publishConfig": {
     "access": "public"
   },
@@ -27,9 +27,9 @@
   ],
   "license": "MIT",
   "peerDependencies": {
-    "@deepseek-ai/cordis": "~4.0.5-alpha.1"
+    "@deepseek-ai/cordis": "~4.0.5-alpha.2"
   },
   "devDependencies": {
-    "@deepseek-ai/cordis": "~4.0.5-alpha.1"
+    "@deepseek-ai/cordis": "~4.0.5-alpha.2"
   }
 }