@zlink-systems/stream-connector 0.18.0 → 0.19.0

package/dist/browser/Runtime/Calls/ZlinkStreamCallBuilders.d.ts

@@ -3,7 +3,7 @@ interface ZlinkStreamConnectorSubmitter {
     readonly options: RequiredZlinkStreamConnectorOptions;
     sendEncoded(kind: ZlinkStreamMessageKind, name: string, payload: ZlinkStreamEncodedPayload, metadata: ZlinkStreamMetadata, compress: boolean, requestSeq: bigint | undefined, signal?: AbortSignal, flow?: ZlinkStreamFlow): Promise<void>;
     requestEncoded(name: string, payload: ZlinkStreamEncodedPayload, metadata: ZlinkStreamMetadata, compress: boolean, timeoutMs: number, signal?: AbortSignal, flow?: ZlinkStreamFlow): Promise<ZlinkStreamEncodedPayload>;
-    waitForMessage<TPayload>(name: string, timeoutMs: number, predicate: (message: ZlinkStreamMessage<TPayload>) => boolean, signal?: AbortSignal): Promise<ZlinkStreamMessage<TPayload>>;
+    waitForMessage<TPayload>(name: string, timeoutMs: number, predicate: (message: ZlinkStreamMessage<TPayload>) => boolean, signal?: AbortSignal): Promise<ZlinkStreamMessage<TPayload> | undefined>;
 }
 export declare class ZlinkStreamSendBuilder implements ZlinkStreamSendCall {
     private readonly connector;

package/dist/browser/Runtime/Calls/ZlinkStreamObservationBuilders.d.ts

@@ -1,7 +1,7 @@
 import { type RequiredZlinkStreamConnectorOptions, type ZlinkStreamExpectNoneCall, type ZlinkStreamMessage, type ZlinkStreamSequenceCall } from '../../Contracts';
 export interface ZlinkStreamMessageWaiter {
     readonly options: RequiredZlinkStreamConnectorOptions;
-    waitForMessage<TPayload>(name: string, timeoutMs: number, predicate: (message: ZlinkStreamMessage<TPayload>) => boolean, signal?: AbortSignal): Promise<ZlinkStreamMessage<TPayload>>;
+    waitForMessage<TPayload>(name: string, timeoutMs: number, predicate: (message: ZlinkStreamMessage<TPayload>) => boolean, signal?: AbortSignal): Promise<ZlinkStreamMessage<TPayload> | undefined>;
 }
 export declare class ZlinkStreamExpectNoneBuilder<TPayload> implements ZlinkStreamExpectNoneCall<TPayload> {
     private readonly connector;

package/dist/browser/Runtime/ZlinkStreamConnector.d.ts

@@ -67,7 +67,19 @@ export declare class DefaultZlinkStreamConnector implements ZlinkStreamConnector
      * `send` and `request` use, so both paths land on one name for one type.
      */
     private observedName;
-    waitForMessage<TPayload>(name: string, timeoutMs: number, predicate: (message: ZlinkStreamMessage<TPayload>) => boolean, signal?: AbortSignal): Promise<ZlinkStreamMessage<TPayload>>;
+    /**
+     * Consumes the first message under `name` that `predicate` accepts, or
+     * resolves `undefined` when `timeoutMs` elapses first.
+     *
+     * A timeout is not a failure here. Each wait surface decides what its own
+     * timeout means — `waitFor` fails on it while `expectNone` succeeds — and
+     * reports that decision as `ValidationFailed` (spec stream-connector 32
+     * §10.1.1; .NET `ZlinkStreamReceivedMessages.WaitForAsync` parity). Losing
+     * the connection the wait observes is the one ending decided here, because
+     * the wait has no place left to observe: that is `Disconnected` for every
+     * surface (§10.1.1).
+     */
+    waitForMessage<TPayload>(name: string, timeoutMs: number, predicate: (message: ZlinkStreamMessage<TPayload>) => boolean, signal?: AbortSignal): Promise<ZlinkStreamMessage<TPayload> | undefined>;
     private encodePayload;
     private decodePayload;
     private decodeWaitPayload;

package/dist/browser/Runtime/ZlinkStreamReceivedMessages.d.ts

@@ -35,10 +35,10 @@ export declare class ZlinkStreamReceivedMessages {
      * observed, and so the caller has its subscription in hand by then.
      *
      * @param onConnectionEnded Called, instead of {@link observer}, when
-     *   {@link resetForNewConnection} abandons this registration because the
+     *   {@link connectionEnded} abandons this registration because the
      *   connection it was watching ended before a message matched (spec
-     *   stream-connector 32 §10.1: "연결이 끝나 대기를 이어갈 수 없으면
-     *   `Disconnected`다").
+     *   stream-connector 32 §10.1.1: "연결이 끝나 대기를 이어갈 수 없으면
+     *   `Disconnected`다", released when that connection ends).
      */
     observe(name: string, observer: EncodedMessageObserver, onConnectionEnded: () => void): Disposable;
     /** Spec stream-connector 32 §10: arrivals under `name` on this connection. */
@@ -57,15 +57,22 @@ export declare class ZlinkStreamReceivedMessages {
      * unlike Java's queued frames, which `closeMessage` releases — so dropping
      * the queue's references is the whole of the release here.
      *
-     * @param replacesAnEarlierConnection False for the very first connection:
-     *   there is no earlier queue or wait to abandon yet. True for a reconnect,
-     *   which also fails every wait surface still registered from the
-     *   connection that just ended with `Disconnected` (Java
-     *   `ZLinkStreamDispatchQueue.resetForNewConnection` parity) — that
-     *   registration was watching a queue this call just discarded, so letting
-     *   it keep watching would silently rebind it to the new connection.
+     * Wait surfaces are not touched here. The ones of the previous connection
+     * were released by {@link connectionEnded} when that connection ended, and
+     * one registered since then is waiting for this connection.
      */
-    resetForNewConnection(replacesAnEarlierConnection: boolean): void;
+    resetForNewConnection(): void;
+    /**
+     * Releases every registered wait surface because the connection it was
+     * watching has ended — a transport loss, a server close, or `close()`.
+     * Spec stream-connector 32 §10.1.1: "푸는 시점은 연결이 끝난 때이지 다음
+     * 연결이 성립한 때가 아니다". The release belongs to the ending, so a wait
+     * does not hang until its own timeout when no next connection comes
+     * (reconnect off, attempts spent) and does not silently rebind to the next
+     * one when it does. The queue and the counts stay: they are rebaselined by
+     * the next {@link resetForNewConnection}, not by the ending (§10).
+     */
+    connectionEnded(): void;
     enqueue(message: ZlinkStreamMessage<ZlinkStreamEncodedPayload>, signal?: AbortSignal): void;
     /**
      * Runs the registered handlers the receive path left queued. `Manual` calls

package/dist/browser/index.global.js

@@ -913,15 +913,18 @@ var ZlinkStreamConnectorBundle = (() => {
       this.timeoutMs = timeoutMs;
       return this;
     }
-    submit(signal) {
+    async submit(signal) {
       var _a;
       this.markExecuted();
-      return this.connector.waitForMessage(
-        this.name,
-        (_a = this.timeoutMs) != null ? _a : this.connector.options.waitTimeoutMs,
-        this.predicate,
-        signal
-      );
+      const timeoutMs = (_a = this.timeoutMs) != null ? _a : this.connector.options.waitTimeoutMs;
+      const message = await this.connector.waitForMessage(this.name, timeoutMs, this.predicate, signal);
+      if (message === void 0) {
+        throw connectorError(
+          "validationFailed" /* ValidationFailed */,
+          `No '${this.name}' message arrived within ${timeoutMs}ms.`
+        );
+      }
+      return message;
     }
     ensureConfigurable() {
       if (this.executed) {
@@ -953,13 +956,9 @@ var ZlinkStreamConnectorBundle = (() => {
       if (this.windowMs === void 0) {
         throw connectorError("validationFailed" /* ValidationFailed */, "expectNone requires within(windowMs).");
       }
-      try {
-        await this.connector.waitForMessage(this.name, this.windowMs, () => true, signal);
-      } catch (error) {
-        if (unwrapStreamError(error).code === "requestTimeout" /* RequestTimeout */) {
-          return;
-        }
-        throw error;
+      const message = await this.connector.waitForMessage(this.name, this.windowMs, () => true, signal);
+      if (message === void 0) {
+        return;
       }
       throw connectorError(
         "validationFailed" /* ValidationFailed */,
@@ -1022,6 +1021,12 @@ var ZlinkStreamConnectorBundle = (() => {
           },
           signal
         );
+        if (message === void 0) {
+          throw connectorError(
+            "validationFailed" /* ValidationFailed */,
+            `The '${this.name}' sequence did not complete within ${timeoutMs}ms.`
+          );
+        }
         messages.push(message);
       }
       return messages;
@@ -1642,10 +1647,10 @@ var ZlinkStreamConnectorBundle = (() => {
      * observed, and so the caller has its subscription in hand by then.
      *
      * @param onConnectionEnded Called, instead of {@link observer}, when
-     *   {@link resetForNewConnection} abandons this registration because the
+     *   {@link connectionEnded} abandons this registration because the
      *   connection it was watching ended before a message matched (spec
-     *   stream-connector 32 §10.1: "연결이 끝나 대기를 이어갈 수 없으면
-     *   `Disconnected`다").
+     *   stream-connector 32 §10.1.1: "연결이 끝나 대기를 이어갈 수 없으면
+     *   `Disconnected`다", released when that connection ends).
      */
     observe(name, observer, onConnectionEnded) {
       validateName(name);
@@ -1688,20 +1693,28 @@ var ZlinkStreamConnectorBundle = (() => {
      * unlike Java's queued frames, which `closeMessage` releases — so dropping
      * the queue's references is the whole of the release here.
      *
-     * @param replacesAnEarlierConnection False for the very first connection:
-     *   there is no earlier queue or wait to abandon yet. True for a reconnect,
-     *   which also fails every wait surface still registered from the
-     *   connection that just ended with `Disconnected` (Java
-     *   `ZLinkStreamDispatchQueue.resetForNewConnection` parity) — that
-     *   registration was watching a queue this call just discarded, so letting
-     *   it keep watching would silently rebind it to the new connection.
+     * Wait surfaces are not touched here. The ones of the previous connection
+     * were released by {@link connectionEnded} when that connection ended, and
+     * one registered since then is waiting for this connection.
      */
-    resetForNewConnection(replacesAnEarlierConnection) {
+    resetForNewConnection() {
       this.receivedCounts.clear();
       this.queue.length = 0;
       this.queueHead = 0;
       this.queuedCount = 0;
-      if (!replacesAnEarlierConnection || this.observers.size === 0) {
+    }
+    /**
+     * Releases every registered wait surface because the connection it was
+     * watching has ended — a transport loss, a server close, or `close()`.
+     * Spec stream-connector 32 §10.1.1: "푸는 시점은 연결이 끝난 때이지 다음
+     * 연결이 성립한 때가 아니다". The release belongs to the ending, so a wait
+     * does not hang until its own timeout when no next connection comes
+     * (reconnect off, attempts spent) and does not silently rebind to the next
+     * one when it does. The queue and the counts stay: they are rebaselined by
+     * the next {@link resetForNewConnection}, not by the ending (§10).
+     */
+    connectionEnded() {
+      if (this.observers.size === 0) {
         return;
       }
       const abandoned = [...this.observers.values()].flatMap((set) => [...set]);
@@ -2141,7 +2154,7 @@ var ZlinkStreamConnectorBundle = (() => {
         this.currentConnection = connection;
         this.connectionGeneration += 1;
         this.disconnectedPublished = false;
-        this.receivedMessages.resetForNewConnection(this.connectionGeneration > 1);
+        this.receivedMessages.resetForNewConnection();
         this.lastInboundAt = Date.now();
         await this.setState("connected" /* Connected */, void 0, signal);
         this.startHeartbeat();
@@ -2202,6 +2215,7 @@ var ZlinkStreamConnectorBundle = (() => {
         errors.push(error);
       }
       this.pendingRequests.failAll({ code: "disconnected" /* Disconnected */, message: "Connector closed." });
+      this.receivedMessages.connectionEnded();
       await this.setState("closed" /* Closed */, void 0, signal);
       this.publishDisconnectedWithoutWaiting(signal);
       if (errors.length === 1) throw errors[0];
@@ -2427,6 +2441,7 @@ var ZlinkStreamConnectorBundle = (() => {
       const connection = this.currentConnection;
       this.currentConnection = void 0;
       this.pendingRequests.failAll(error);
+      this.receivedMessages.connectionEnded();
       try {
         await (connection == null ? void 0 : connection.close());
       } catch {
@@ -2920,6 +2935,18 @@ var ZlinkStreamConnectorBundle = (() => {
       validateName(name);
       return name;
     }
+    /**
+     * Consumes the first message under `name` that `predicate` accepts, or
+     * resolves `undefined` when `timeoutMs` elapses first.
+     *
+     * A timeout is not a failure here. Each wait surface decides what its own
+     * timeout means — `waitFor` fails on it while `expectNone` succeeds — and
+     * reports that decision as `ValidationFailed` (spec stream-connector 32
+     * §10.1.1; .NET `ZlinkStreamReceivedMessages.WaitForAsync` parity). Losing
+     * the connection the wait observes is the one ending decided here, because
+     * the wait has no place left to observe: that is `Disconnected` for every
+     * surface (§10.1.1).
+     */
     waitForMessage(name, timeoutMs, predicate, signal) {
       validateName(name);
       if (!Number.isFinite(timeoutMs) || timeoutMs < 0) {
@@ -2947,9 +2974,7 @@ var ZlinkStreamConnectorBundle = (() => {
             resolve(message);
           }
         };
-        timer = setTimeout(() => {
-          finish(connectorError("requestTimeout" /* RequestTimeout */, "Wait for stream message timed out."));
-        }, timeoutMs);
+        timer = setTimeout(() => finish(), timeoutMs);
         signal == null ? void 0 : signal.addEventListener("abort", onAbort, { once: true });
         disposable = this.receivedMessages.observe(name, (message) => {
           if (done) {

package/dist/browser/index.mjs

@@ -861,14 +861,17 @@ var ZlinkStreamWaitBuilder = class {
     this.timeoutMs = timeoutMs;
     return this;
   }
-  submit(signal) {
+  async submit(signal) {
     this.markExecuted();
-    return this.connector.waitForMessage(
-      this.name,
-      this.timeoutMs ?? this.connector.options.waitTimeoutMs,
-      this.predicate,
-      signal
-    );
+    const timeoutMs = this.timeoutMs ?? this.connector.options.waitTimeoutMs;
+    const message = await this.connector.waitForMessage(this.name, timeoutMs, this.predicate, signal);
+    if (message === void 0) {
+      throw connectorError(
+        "validationFailed" /* ValidationFailed */,
+        `No '${this.name}' message arrived within ${timeoutMs}ms.`
+      );
+    }
+    return message;
   }
   ensureConfigurable() {
     if (this.executed) {
@@ -900,13 +903,9 @@ var ZlinkStreamExpectNoneBuilder = class {
     if (this.windowMs === void 0) {
       throw connectorError("validationFailed" /* ValidationFailed */, "expectNone requires within(windowMs).");
     }
-    try {
-      await this.connector.waitForMessage(this.name, this.windowMs, () => true, signal);
-    } catch (error) {
-      if (unwrapStreamError(error).code === "requestTimeout" /* RequestTimeout */) {
-        return;
-      }
-      throw error;
+    const message = await this.connector.waitForMessage(this.name, this.windowMs, () => true, signal);
+    if (message === void 0) {
+      return;
     }
     throw connectorError(
       "validationFailed" /* ValidationFailed */,
@@ -968,6 +967,12 @@ var ZlinkStreamSequenceBuilder = class {
         },
         signal
       );
+      if (message === void 0) {
+        throw connectorError(
+          "validationFailed" /* ValidationFailed */,
+          `The '${this.name}' sequence did not complete within ${timeoutMs}ms.`
+        );
+      }
       messages.push(message);
     }
     return messages;
@@ -1582,10 +1587,10 @@ var ZlinkStreamReceivedMessages = class {
    * observed, and so the caller has its subscription in hand by then.
    *
    * @param onConnectionEnded Called, instead of {@link observer}, when
-   *   {@link resetForNewConnection} abandons this registration because the
+   *   {@link connectionEnded} abandons this registration because the
    *   connection it was watching ended before a message matched (spec
-   *   stream-connector 32 §10.1: "연결이 끝나 대기를 이어갈 수 없으면
-   *   `Disconnected`다").
+   *   stream-connector 32 §10.1.1: "연결이 끝나 대기를 이어갈 수 없으면
+   *   `Disconnected`다", released when that connection ends).
    */
   observe(name, observer, onConnectionEnded) {
     validateName(name);
@@ -1626,20 +1631,28 @@ var ZlinkStreamReceivedMessages = class {
    * unlike Java's queued frames, which `closeMessage` releases — so dropping
    * the queue's references is the whole of the release here.
    *
-   * @param replacesAnEarlierConnection False for the very first connection:
-   *   there is no earlier queue or wait to abandon yet. True for a reconnect,
-   *   which also fails every wait surface still registered from the
-   *   connection that just ended with `Disconnected` (Java
-   *   `ZLinkStreamDispatchQueue.resetForNewConnection` parity) — that
-   *   registration was watching a queue this call just discarded, so letting
-   *   it keep watching would silently rebind it to the new connection.
+   * Wait surfaces are not touched here. The ones of the previous connection
+   * were released by {@link connectionEnded} when that connection ended, and
+   * one registered since then is waiting for this connection.
    */
-  resetForNewConnection(replacesAnEarlierConnection) {
+  resetForNewConnection() {
     this.receivedCounts.clear();
     this.queue.length = 0;
     this.queueHead = 0;
     this.queuedCount = 0;
-    if (!replacesAnEarlierConnection || this.observers.size === 0) {
+  }
+  /**
+   * Releases every registered wait surface because the connection it was
+   * watching has ended — a transport loss, a server close, or `close()`.
+   * Spec stream-connector 32 §10.1.1: "푸는 시점은 연결이 끝난 때이지 다음
+   * 연결이 성립한 때가 아니다". The release belongs to the ending, so a wait
+   * does not hang until its own timeout when no next connection comes
+   * (reconnect off, attempts spent) and does not silently rebind to the next
+   * one when it does. The queue and the counts stay: they are rebaselined by
+   * the next {@link resetForNewConnection}, not by the ending (§10).
+   */
+  connectionEnded() {
+    if (this.observers.size === 0) {
       return;
     }
     const abandoned = [...this.observers.values()].flatMap((set) => [...set]);
@@ -2073,7 +2086,7 @@ var ZlinkStreamConnectorLifecycle = class {
       this.currentConnection = connection;
       this.connectionGeneration += 1;
       this.disconnectedPublished = false;
-      this.receivedMessages.resetForNewConnection(this.connectionGeneration > 1);
+      this.receivedMessages.resetForNewConnection();
       this.lastInboundAt = Date.now();
       await this.setState("connected" /* Connected */, void 0, signal);
       this.startHeartbeat();
@@ -2133,6 +2146,7 @@ var ZlinkStreamConnectorLifecycle = class {
       errors.push(error);
     }
     this.pendingRequests.failAll({ code: "disconnected" /* Disconnected */, message: "Connector closed." });
+    this.receivedMessages.connectionEnded();
     await this.setState("closed" /* Closed */, void 0, signal);
     this.publishDisconnectedWithoutWaiting(signal);
     if (errors.length === 1) throw errors[0];
@@ -2354,6 +2368,7 @@ var ZlinkStreamConnectorLifecycle = class {
     const connection = this.currentConnection;
     this.currentConnection = void 0;
     this.pendingRequests.failAll(error);
+    this.receivedMessages.connectionEnded();
     try {
       await connection?.close();
     } catch {
@@ -2846,6 +2861,18 @@ var DefaultZlinkStreamConnector = class {
     validateName(name);
     return name;
   }
+  /**
+   * Consumes the first message under `name` that `predicate` accepts, or
+   * resolves `undefined` when `timeoutMs` elapses first.
+   *
+   * A timeout is not a failure here. Each wait surface decides what its own
+   * timeout means — `waitFor` fails on it while `expectNone` succeeds — and
+   * reports that decision as `ValidationFailed` (spec stream-connector 32
+   * §10.1.1; .NET `ZlinkStreamReceivedMessages.WaitForAsync` parity). Losing
+   * the connection the wait observes is the one ending decided here, because
+   * the wait has no place left to observe: that is `Disconnected` for every
+   * surface (§10.1.1).
+   */
   waitForMessage(name, timeoutMs, predicate, signal) {
     validateName(name);
     if (!Number.isFinite(timeoutMs) || timeoutMs < 0) {
@@ -2873,9 +2900,7 @@ var DefaultZlinkStreamConnector = class {
           resolve(message);
         }
       };
-      timer = setTimeout(() => {
-        finish(connectorError("requestTimeout" /* RequestTimeout */, "Wait for stream message timed out."));
-      }, timeoutMs);
+      timer = setTimeout(() => finish(), timeoutMs);
       signal?.addEventListener("abort", onAbort, { once: true });
       disposable = this.receivedMessages.observe(name, (message) => {
         if (done) {

package/dist/package.json

@@ -0,0 +1 @@
+{"type":"commonjs"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zlink-systems/stream-connector",
-  "version": "0.18.0",
+  "version": "0.19.0",
   "license": "SEE LICENSE IN LICENSE",
   "repository": {
     "type": "git",
@@ -12,6 +12,7 @@
   "types": "dist/browser/index.d.ts",
   "files": [
     "dist/browser",
+    "dist/package.json",
     "LICENSE"
   ],
   "exports": {
@@ -21,6 +22,6 @@
     }
   },
   "dependencies": {
-    "@zlink-systems/stream-wire": "0.18.0"
+    "@zlink-systems/stream-wire": "0.19.0"
   }
 }