@x1a0f3n9/dsh-timeout 0.1.7-rc.3 → 0.2.1-rc.3

package/README.i18n.yaml

@@ -5,60 +5,60 @@
 /:
   en: 118428acb1b2d2e4
   zh: e5ca5ae92e8a7e4b
-/x1a0f3n9-dsh-timeout:
-  en: 2fa1744a61d4d88b
-  zh: 7a3ea7ac9f75ce6b
-/x1a0f3n9-dsh-timeout/summary:
+/deepseek-ai-dsh-timeout:
+  en: af0ef4476e8b699f
+  zh: 1071d810d1080026
+/deepseek-ai-dsh-timeout/summary:
   en: 13fc36a866f4ae6d
   zh: 02a9ab4bd48e968a
-/x1a0f3n9-dsh-timeout/table-of-contents:
+/deepseek-ai-dsh-timeout/table-of-contents:
   en: d152484eb41ac6b4
   zh: 09388d293f9be9cb
-/x1a0f3n9-dsh-timeout/use-this-package:
+/deepseek-ai-dsh-timeout/use-this-package:
   en: f000e79268bb4b39
   zh: 82c40259b95776be
-/x1a0f3n9-dsh-timeout/use-this-package/clamping-a-timeout-hint:
+/deepseek-ai-dsh-timeout/use-this-package/clamping-a-timeout-hint:
   en: f8c517a0c27ebeec
   zh: 0b6eed0130330349
-/x1a0f3n9-dsh-timeout/use-this-package/running-work-under-a-deadline:
+/deepseek-ai-dsh-timeout/use-this-package/running-work-under-a-deadline:
   en: 5cfa732a396484a6
   zh: d114cd5ea1ddeb3f
-/x1a0f3n9-dsh-timeout/use-this-package/classifying-the-outcome:
+/deepseek-ai-dsh-timeout/use-this-package/classifying-the-outcome:
   en: 0c1e99daa88e0ea0
   zh: fc92bc0add2e9a49
-/x1a0f3n9-dsh-timeout/use-this-package/streaming-with-an-idle-watchdog:
+/deepseek-ai-dsh-timeout/use-this-package/streaming-with-an-idle-watchdog:
   en: f464a16371ff00d1
   zh: 3c62c560c9dbc804
-/x1a0f3n9-dsh-timeout/use-this-package/what-does-not-get-a-timeout:
+/deepseek-ai-dsh-timeout/use-this-package/what-does-not-get-a-timeout:
   en: 73e04894d01ddb23
   zh: 4830e47cc55143ff
-/x1a0f3n9-dsh-timeout/understand-the-implementation:
+/deepseek-ai-dsh-timeout/understand-the-implementation:
   en: 6c052aa1171a2e3b
   zh: 2a37575eb6059cc9
-/x1a0f3n9-dsh-timeout/understand-the-implementation/source-map:
-  en: be1b396f4153b9d0
-  zh: a762ab1642b3431e
-/x1a0f3n9-dsh-timeout/understand-the-implementation/how-a-deadline-fuses-sources:
+/deepseek-ai-dsh-timeout/understand-the-implementation/source-map:
+  en: b21d7b48571ebfba
+  zh: e31188863ece408d
+/deepseek-ai-dsh-timeout/understand-the-implementation/how-a-deadline-fuses-sources:
   en: 940080c53d1d0dac
   zh: b86e7f51434a3f2c
-/x1a0f3n9-dsh-timeout/understand-the-implementation/the-no-timeout-sentinel:
+/deepseek-ai-dsh-timeout/understand-the-implementation/the-no-timeout-sentinel:
   en: ceea0b46e6b8e15f
   zh: de87dccf08764061
-/x1a0f3n9-dsh-timeout/understand-the-implementation/why-an-idle-watchdog-rearms:
-  en: 7200cfa587c53a9c
-  zh: 09d6b67dc1a31c5e
-/x1a0f3n9-dsh-timeout/further-exploration:
+/deepseek-ai-dsh-timeout/understand-the-implementation/why-an-idle-watchdog-rearms:
+  en: f7cd0e8ba2937f0f
+  zh: d17d546c5587b04e
+/deepseek-ai-dsh-timeout/further-exploration:
   en: 4c29a947e28047ad
   zh: d80f5ecb50b16203
-/x1a0f3n9-dsh-timeout/model-experience:
+/deepseek-ai-dsh-timeout/model-experience:
   en: 5c35c77e4625b8ac
   zh: 8142da11ba1a6d11
-/x1a0f3n9-dsh-timeout/model-experience/kv-cache-effect:
+/deepseek-ai-dsh-timeout/model-experience/kv-cache-effect:
   en: 04cc18d90bf9382d
   zh: 2c8b75063c46c620
-/x1a0f3n9-dsh-timeout/known-limitations-and-deferred-work:
+/deepseek-ai-dsh-timeout/known-limitations-and-deferred-work:
   en: cff4b9d3cfc23a97
   zh: 9eb52fbe4c8a6c30
-/x1a0f3n9-dsh-timeout/known-limitations-and-deferred-work/dev-note:
+/deepseek-ai-dsh-timeout/known-limitations-and-deferred-work/dev-note:
   en: e67f633dc6fe7773
   zh: 3bb0c20c93f16f98

package/README.md

@@ -92,7 +92,6 @@ The library is built on one boundary: share the timing and classification, keep
 | File | Role |
 |---|---|
 | [`src/index.ts`](src/index.ts) | `clampTimeout`, `deadline`, `idleWatchdog`, `timeoutOf`, `TimeoutReason`, `MAX_TIMER_DELAY_MS` |
-| — | No runtime invariant companion is published; this pure utility owns no event stream or mutable runtime data; its value algebra is enforced by unit tests. |
 
 ### How a deadline fuses sources
 
@@ -104,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

@@ -92,7 +92,6 @@ timer 只在某个迭代器 `next()` 尚未完成时启动，并会因不产生
 | 文件 | 职责 |
 |---|---|
 | [`src/index.ts`](src/index.ts) | `clampTimeout`、`deadline`、`idleWatchdog`、`timeoutOf`、`TimeoutReason`、`MAX_TIMER_DELAY_MS` |
-| — | 不发布运行时不变式伴生入口；这个纯工具不拥有事件流或可变运行时数据；其值代数约束由单元测试保障。 |
 
 ### deadline 如何融合来源
 
@@ -104,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": "@x1a0f3n9/dsh-timeout",
   "description": "Zero-dependency timeout/deadline primitive: clampTimeout, deadline, timeoutOf, TimeoutReason (timing + classification only, no termination)",
-  "version": "0.1.7-rc.3",
+  "version": "0.2.1-rc.3",
   "publishConfig": {
     "access": "public"
   },
@@ -27,9 +27,9 @@
   ],
   "license": "MIT",
   "peerDependencies": {
-    "@deepseek-ai/cordis": "~4.0.4"
+    "@deepseek-ai/cordis": "~4.0.5"
   },
   "devDependencies": {
-    "@deepseek-ai/cordis": "~4.0.4"
+    "@deepseek-ai/cordis": "~4.0.5"
   }
 }