@ultimat3/realtime 27.12.0 → 27.13.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/realtime",
-  "version": "27.12.0",
+  "version": "27.13.1",
   "description": "Three-tier realtime: channels, live queries, local-first sync — one protocol, one mutator shape",
   "license": "MIT",
   "type": "module",
@@ -40,10 +40,10 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/core": "27.12.0",
-    "@ultimat3/entity": "27.12.0",
-    "@ultimat3/policy": "27.12.0",
-    "@ultimat3/query": "27.12.0",
+    "@ultimat3/core": "27.13.1",
+    "@ultimat3/entity": "27.13.1",
+    "@ultimat3/policy": "27.13.1",
+    "@ultimat3/query": "27.13.1",
     "nats": "2.29.3"
   }
 }

package/src/nats-client.ts

@@ -43,6 +43,12 @@ export interface NatsClient {
   readonly connected: boolean;
   publish(subject: string, payload: Uint8Array): void;
   subscribe(subject: string, handler: NatsMessageHandler): NatsSubscription;
+  /**
+   * Answers once the server has processed every line sent before it — a `SUB` included. `subscribe`
+   * only WRITES that line: a message another connection publishes before the server reads it is
+   * not delivered, so "subscribed" means flushed.
+   */
+  flush(): Promise<void>;
   request(subject: string, payload: Uint8Array, options?: NatsRequestOptions): Promise<NatsMessage>;
   requestMany(
     subject: string,

package/src/nats-fake.ts

@@ -167,6 +167,11 @@ class FakeNatsClient implements NatsClient {
     };
   }
 
+  /** The broker delivers synchronously, so a subscription is held the moment it is added. */
+  async flush(): Promise<void> {
+    this.#assertOpen();
+  }
+
   async request(
     subject: string,
     payload: Uint8Array,

package/src/nats-lib-client.ts

@@ -14,7 +14,7 @@
 // This header said "every failure leaves here as an `UltimateError`" until 2026-08, which a reader
 // took as a guarantee it never was.
 
-import { finiteOption, renderThrowable } from '@ultimat3/core';
+import { finiteOption, isUltimateError, renderThrowable } from '@ultimat3/core';
 import { connect, Events, headers, Match, type Msg, type MsgHdrs, type NatsConnection } from 'nats';
 import { TransportUnavailableError } from './errors';
 import {
@@ -113,6 +113,25 @@ class LibNatsClient implements NatsClient {
     return { unsubscribe: () => subscription.unsubscribe() };
   }
 
+  async flush(): Promise<void> {
+    // Bounded like a request: the library's flush waits on a PONG forever, and a server that went
+    // silent (`nats-black-hole.live.test.ts`) never sends one.
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    const late = new Promise<never>((_, reject) => {
+      timer = setTimeout(
+        () => reject(unavailable(this.#target, `flush unanswered after ${this.#timeoutMs}ms`)),
+        this.#timeoutMs,
+      );
+    });
+    try {
+      await Promise.race([this.#connection.flush(), late]);
+    } catch (error) {
+      throw isUltimateError(error) ? error : unavailable(this.#target, `flush: ${describe(error)}`);
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+
   async request(
     subject: string,
     payload: Uint8Array,

package/src/nats-transport.ts

@@ -204,6 +204,11 @@ export class NatsTransport implements Transport {
       },
       (call) => this.#translating(`subscribe to ${subject}`, call),
     );
+    // Resolved only once the server HOLDS it: a publish from another process in the gap between
+    // writing the SUB and the server reading it was lost (`nats-black-hole.live.test.ts`, CI run
+    // 39145087176). Mid-reconnect there is no server to ask: the library re-sends the SUB on the
+    // way back, and `onReconnect` reports that gap. A flush that fails is that same case.
+    if (client.connected) await client.flush().catch(() => undefined);
     return { subject, unsubscribe: release };
   }