on-zero 0.6.7 → 0.6.9

package/dist/cjs/httpPullTransport.cjs

@@ -45,6 +45,10 @@ function installHttpPullTransport(opts) {
     nativeWebSocket: previousWebSocket,
     sockets: /* @__PURE__ */new Set(),
     pullIntervalMs: opts.pullIntervalMs,
+    wakeEnabled: opts.wake ?? false,
+    queryTransform: opts.queryTransform,
+    queryForward: opts.queryForward === true,
+    queryAware: opts.queryTransform !== void 0 || opts.queryForward === true,
     nextPokeID: 0,
     transientFailureCount: 0
   };
@@ -124,12 +128,22 @@ class ZeroHttpSocket {
   wsid;
   cookie;
   pendingGotQueriesPatch = [];
+  // query-aware extension state: the accumulated un-acked desired-query delta
+  // to ship, a client-side query-state version that bumps on each change, and
+  // the version/length of the delta the in-flight pull sent (to clear the
+  // acked prefix on the server's ack).
+  desiredQueryPatch = [];
+  queryVersion = 0;
+  sentQueryVersion;
+  sentQueryPatchLen = 0;
   pullInFlight;
   pullAfterCurrent = false;
   pushChain = Promise.resolve();
   nextLocalCookieID;
   openTimer;
   pullTimer;
+  wakeSocket;
+  wakeReconnectTimer;
   addEventListener(type, listener) {
     if (listener) this.listeners[type]?.add(listener);
   }
@@ -174,6 +188,7 @@ class ZeroHttpSocket {
     if (this.readyState === this.CLOSED) return;
     if (this.openTimer) clearTimeout(this.openTimer);
     if (this.pullTimer) clearInterval(this.pullTimer);
+    this.closeWakeChannel();
     this.readyState = this.CLOSED;
     this.state.sockets.delete(this);
     this.emit("close", {
@@ -185,7 +200,8 @@ class ZeroHttpSocket {
   pull() {
     if (this.readyState !== this.OPEN) return Promise.resolve();
     if (this.pullInFlight) return this.pullInFlight;
-    this.pullInFlight = this.fetchPull(this.clientGroupID, this.cookie).then(response => {
+    this.pullInFlight = this.fetchPull(this.clientGroupID, this.cookie, true).then(response => {
+      if (this.state.queryAware) this.applyServerGotQueries(response);
       if (response.unchanged) {
         this.emitGotQueriesPatch(response.cookie);
         return;
@@ -216,11 +232,96 @@ class ZeroHttpSocket {
         this.run(this.pull());
       }, this.state.pullIntervalMs);
     }
+    if (this.state.wakeEnabled) this.openWakeChannel();
+  }
+  // notification-only wake channel: a real WebSocket to <origin>/wake that
+  // carries no data. any frame means "pull now", so a wake triggers an
+  // immediate (coalesced) pull — push-shaped propagation without waiting on
+  // the poll interval. advisory only: if it drops we reconnect, and the
+  // interval poll remains the safety net that guarantees convergence.
+  openWakeChannel() {
+    const Native = this.state.nativeWebSocket;
+    if (!Native || this.wakeSocket || this.readyState !== this.OPEN) return;
+    const wsBase = this.state.originString.replace(/^http/, "ws");
+    const url = `${wsBase}/wake?clientID=${encodeURIComponent(this.clientID)}`;
+    let socket;
+    try {
+      socket = new Native(url);
+    } catch {
+      return;
+    }
+    this.wakeSocket = socket;
+    const reconnect = () => {
+      if (this.wakeSocket !== socket) return;
+      this.wakeSocket = void 0;
+      if (this.readyState !== this.OPEN || this.wakeReconnectTimer) return;
+      this.wakeReconnectTimer = setTimeout(() => {
+        this.wakeReconnectTimer = void 0;
+        this.openWakeChannel();
+      }, 500);
+    };
+    socket.onmessage = () => this.requestPullAfterCurrent();
+    socket.onclose = reconnect;
+    socket.onerror = reconnect;
+  }
+  closeWakeChannel() {
+    if (this.wakeReconnectTimer) {
+      clearTimeout(this.wakeReconnectTimer);
+      this.wakeReconnectTimer = void 0;
+    }
+    const socket = this.wakeSocket;
+    this.wakeSocket = void 0;
+    if (socket) {
+      try {
+        socket.close();
+      } catch {}
+    }
   }
   queueDesiredQueries(body) {
     const desiredQueriesPatch = body?.desiredQueriesPatch;
     if (!Array.isArray(desiredQueriesPatch)) return;
-    this.pendingGotQueriesPatch.push(...gotQueriesPatch(desiredQueriesPatch));
+    if (!this.state.queryAware) {
+      this.pendingGotQueriesPatch.push(...gotQueriesPatch(desiredQueriesPatch));
+      return;
+    }
+    const transform = this.state.queryTransform;
+    for (const op of desiredQueriesPatch) {
+      if (op.op === "clear") {
+        this.desiredQueryPatch.push({
+          op: "clear"
+        });
+      } else if (op.op === "del") {
+        this.desiredQueryPatch.push({
+          op: "del",
+          hash: op.hash
+        });
+      } else if (op.op === "put") {
+        const inline = op.ast;
+        const name = op.name ?? "";
+        const args = op.args ?? [];
+        if (this.state.queryForward) {
+          this.desiredQueryPatch.push({
+            op: "put",
+            hash: op.hash,
+            name,
+            args
+          });
+        } else if (inline !== void 0) {
+          this.desiredQueryPatch.push({
+            op: "put",
+            hash: op.hash,
+            ast: inline
+          });
+        } else if (transform) {
+          this.desiredQueryPatch.push({
+            op: "put",
+            hash: op.hash,
+            ast: transform(name, args)
+          });
+        }
+      }
+    }
+    this.queryVersion++;
   }
   async push(body) {
     const response = await this.postJSON("/push", body);
@@ -242,8 +343,21 @@ class ZeroHttpSocket {
     }
     this.run(this.pull());
   }
+  // in query-aware mode the got-query ack is authoritative from the server:
+  // take the server's gotQueries.patch as the got patch to emit (replacing
+  // local synthesis), and clear the acked prefix of the shipped desired delta
+  // once the server acks that version (the ack never leads its row effects —
+  // invariant 13 — so the client marks a query got only after its rows land).
+  applyServerGotQueries(response) {
+    const got = response.gotQueries;
+    this.pendingGotQueriesPatch = got ? got.patch : [];
+    if (got && this.sentQueryVersion !== void 0 && got.version >= this.sentQueryVersion) {
+      this.desiredQueryPatch.splice(0, this.sentQueryPatchLen);
+      this.sentQueryVersion = void 0;
+    }
+  }
   async answerMutationRecoveryPull(body) {
-    const response = await this.fetchPull(body.clientGroupID, body.cookie);
+    const response = await this.fetchPull(body.clientGroupID, body.cookie, false);
     const cookie = toWebSocketCookie(response.cookie);
     this.emitMessage(["pull", {
       requestID: body.requestID,
@@ -251,12 +365,23 @@ class ZeroHttpSocket {
       lastMutationIDChanges: response.unchanged ? {} : response.lastMutationIDChanges
     }]);
   }
-  async fetchPull(clientGroupID, cookie) {
-    return await this.postJSON("/pull", {
+  async fetchPull(clientGroupID, cookie, includeQueries) {
+    const body = {
       clientID: this.clientID,
       clientGroupID,
       cookie: toHttpCookie(cookie)
-    });
+    };
+    if (includeQueries && this.state.queryAware && this.desiredQueryPatch.length > 0) {
+      this.sentQueryVersion = this.queryVersion;
+      this.sentQueryPatchLen = this.desiredQueryPatch.length;
+      body.queries = {
+        version: this.queryVersion,
+        patch: [...this.desiredQueryPatch]
+      };
+    } else {
+      this.sentQueryVersion = void 0;
+    }
+    return await this.postJSON("/pull", body);
   }
   async postJSON(path, body) {
     const response = await this.state.fetch(`${this.state.originString}${path}`, {
@@ -303,9 +428,14 @@ class ZeroHttpSocket {
     this.close(1011, errorMessage(error));
   }
   emitPoke(response) {
-    const nextCookie = toWebSocketCookie(response.cookie);
-    if (isStaleCookie(this.cookie, response.cookie)) {
+    const currentServer = toHttpCookie(this.cookie);
+    let nextCookie;
+    if (currentServer !== null && response.cookie < currentServer) {
       throw new Error(`zero-http pull returned stale cookie ${response.cookie} for ${this.cookie}`);
+    } else if (currentServer !== null && response.cookie === currentServer) {
+      nextCookie = toLocalWebSocketCookie(response.cookie, ++this.nextLocalCookieID);
+    } else {
+      nextCookie = toWebSocketCookie(response.cookie);
     }
     const pokeID = `zero-http-${++this.state.nextPokeID}`;
     const gotQueries = this.pendingGotQueriesPatch;
@@ -432,10 +562,6 @@ function toWebSocketCookie(cookie) {
 function toLocalWebSocketCookie(cookie, localID) {
   return `${String(cookie).padStart(COOKIE_WIDTH, "0")}#${String(localID).padStart(6, "0")}`;
 }
-function isStaleCookie(current, next) {
-  const currentNumber = toHttpCookie(current);
-  return currentNumber !== null && next <= currentNumber;
-}
 function errorMessage(error) {
   return error instanceof Error ? error.message : String(error);
 }

package/dist/cjs/httpPullTransport.native.js

@@ -177,6 +177,7 @@ function installHttpPullTransport(opts) {
   if (!fetchImpl) {
     throw new Error("installHttpPullTransport requires a fetch implementation");
   }
+  var _opts_wake;
   var state = {
     origin: new URL(opts.origin),
     originString: trimTrailingSlash(new URL(opts.origin).toString()),
@@ -187,6 +188,10 @@ function installHttpPullTransport(opts) {
     nativeWebSocket: previousWebSocket,
     sockets: /* @__PURE__ */new Set(),
     pullIntervalMs: opts.pullIntervalMs,
+    wakeEnabled: (_opts_wake = opts.wake) !== null && _opts_wake !== void 0 ? _opts_wake : false,
+    queryTransform: opts.queryTransform,
+    queryForward: opts.queryForward === true,
+    queryAware: opts.queryTransform !== void 0 || opts.queryForward === true,
     nextPokeID: 0,
     transientFailureCount: 0
   };
@@ -250,12 +255,18 @@ var ZeroHttpSocket = /* @__PURE__ */function () {
     _define_property(this, "wsid", void 0);
     _define_property(this, "cookie", void 0);
     _define_property(this, "pendingGotQueriesPatch", void 0);
+    _define_property(this, "desiredQueryPatch", void 0);
+    _define_property(this, "queryVersion", void 0);
+    _define_property(this, "sentQueryVersion", void 0);
+    _define_property(this, "sentQueryPatchLen", void 0);
     _define_property(this, "pullInFlight", void 0);
     _define_property(this, "pullAfterCurrent", void 0);
     _define_property(this, "pushChain", void 0);
     _define_property(this, "nextLocalCookieID", void 0);
     _define_property(this, "openTimer", void 0);
     _define_property(this, "pullTimer", void 0);
+    _define_property(this, "wakeSocket", void 0);
+    _define_property(this, "wakeReconnectTimer", void 0);
     this.state = state;
     this.CONNECTING = 0;
     this.OPEN = 1;
@@ -269,6 +280,9 @@ var ZeroHttpSocket = /* @__PURE__ */function () {
       error: /* @__PURE__ */new Set()
     };
     this.pendingGotQueriesPatch = [];
+    this.desiredQueryPatch = [];
+    this.queryVersion = 0;
+    this.sentQueryPatchLen = 0;
     this.pullAfterCurrent = false;
     this.pushChain = Promise.resolve();
     this.connectURL = toHttpURL(url);
@@ -349,6 +363,7 @@ var ZeroHttpSocket = /* @__PURE__ */function () {
       if (this.readyState === this.CLOSED) return;
       if (this.openTimer) clearTimeout(this.openTimer);
       if (this.pullTimer) clearInterval(this.pullTimer);
+      this.closeWakeChannel();
       this.readyState = this.CLOSED;
       this.state.sockets.delete(this);
       this.emit("close", {
@@ -363,7 +378,8 @@ var ZeroHttpSocket = /* @__PURE__ */function () {
       var _this = this;
       if (this.readyState !== this.OPEN) return Promise.resolve();
       if (this.pullInFlight) return this.pullInFlight;
-      this.pullInFlight = this.fetchPull(this.clientGroupID, this.cookie).then(function (response) {
+      this.pullInFlight = this.fetchPull(this.clientGroupID, this.cookie, true).then(function (response) {
+        if (_this.state.queryAware) _this.applyServerGotQueries(response);
         if (response.unchanged) {
           _this.emitGotQueriesPatch(response.cookie);
           return;
@@ -399,13 +415,129 @@ var ZeroHttpSocket = /* @__PURE__ */function () {
           _this.run(_this.pull());
         }, this.state.pullIntervalMs);
       }
+      if (this.state.wakeEnabled) this.openWakeChannel();
+    }
+  }, {
+    key: "openWakeChannel",
+    value:
+    // notification-only wake channel: a real WebSocket to <origin>/wake that
+    // carries no data. any frame means "pull now", so a wake triggers an
+    // immediate (coalesced) pull — push-shaped propagation without waiting on
+    // the poll interval. advisory only: if it drops we reconnect, and the
+    // interval poll remains the safety net that guarantees convergence.
+    function openWakeChannel() {
+      var _this = this;
+      var Native = this.state.nativeWebSocket;
+      if (!Native || this.wakeSocket || this.readyState !== this.OPEN) return;
+      var wsBase = this.state.originString.replace(/^http/, "ws");
+      var url = `${wsBase}/wake?clientID=${encodeURIComponent(this.clientID)}`;
+      var socket;
+      try {
+        socket = new Native(url);
+      } catch (e) {
+        return;
+      }
+      this.wakeSocket = socket;
+      var reconnect = function () {
+        if (_this.wakeSocket !== socket) return;
+        _this.wakeSocket = void 0;
+        if (_this.readyState !== _this.OPEN || _this.wakeReconnectTimer) return;
+        _this.wakeReconnectTimer = setTimeout(function () {
+          _this.wakeReconnectTimer = void 0;
+          _this.openWakeChannel();
+        }, 500);
+      };
+      socket.onmessage = function () {
+        return _this.requestPullAfterCurrent();
+      };
+      socket.onclose = reconnect;
+      socket.onerror = reconnect;
+    }
+  }, {
+    key: "closeWakeChannel",
+    value: function closeWakeChannel() {
+      if (this.wakeReconnectTimer) {
+        clearTimeout(this.wakeReconnectTimer);
+        this.wakeReconnectTimer = void 0;
+      }
+      var socket = this.wakeSocket;
+      this.wakeSocket = void 0;
+      if (socket) {
+        try {
+          socket.close();
+        } catch (e) {}
+      }
     }
   }, {
     key: "queueDesiredQueries",
-    value: function queueDesiredQueries(body) {
+    value:
+    // best effort: an already-closing wake socket is harmless
+    function queueDesiredQueries(body) {
       var desiredQueriesPatch = body === null || body === void 0 ? void 0 : body.desiredQueriesPatch;
       if (!Array.isArray(desiredQueriesPatch)) return;
-      this.pendingGotQueriesPatch.push(...gotQueriesPatch(desiredQueriesPatch));
+      if (!this.state.queryAware) {
+        this.pendingGotQueriesPatch.push(...gotQueriesPatch(desiredQueriesPatch));
+        return;
+      }
+      var transform = this.state.queryTransform;
+      var _iteratorNormalCompletion = true,
+        _didIteratorError = false,
+        _iteratorError = void 0;
+      try {
+        for (var _iterator = desiredQueriesPatch[Symbol.iterator](), _step; !(_iteratorNormalCompletion = (_step = _iterator.next()).done); _iteratorNormalCompletion = true) {
+          var op = _step.value;
+          if (op.op === "clear") {
+            this.desiredQueryPatch.push({
+              op: "clear"
+            });
+          } else if (op.op === "del") {
+            this.desiredQueryPatch.push({
+              op: "del",
+              hash: op.hash
+            });
+          } else if (op.op === "put") {
+            var inline = op.ast;
+            var _op_name;
+            var name = (_op_name = op.name) !== null && _op_name !== void 0 ? _op_name : "";
+            var _op_args;
+            var args = (_op_args = op.args) !== null && _op_args !== void 0 ? _op_args : [];
+            if (this.state.queryForward) {
+              this.desiredQueryPatch.push({
+                op: "put",
+                hash: op.hash,
+                name,
+                args
+              });
+            } else if (inline !== void 0) {
+              this.desiredQueryPatch.push({
+                op: "put",
+                hash: op.hash,
+                ast: inline
+              });
+            } else if (transform) {
+              this.desiredQueryPatch.push({
+                op: "put",
+                hash: op.hash,
+                ast: transform(name, args)
+              });
+            }
+          }
+        }
+      } catch (err) {
+        _didIteratorError = true;
+        _iteratorError = err;
+      } finally {
+        try {
+          if (!_iteratorNormalCompletion && _iterator.return != null) {
+            _iterator.return();
+          }
+        } finally {
+          if (_didIteratorError) {
+            throw _iteratorError;
+          }
+        }
+      }
+      this.queryVersion++;
     }
   }, {
     key: "push",
@@ -434,10 +566,26 @@ var ZeroHttpSocket = /* @__PURE__ */function () {
       }
       this.run(this.pull());
     }
+  }, {
+    key: "applyServerGotQueries",
+    value:
+    // in query-aware mode the got-query ack is authoritative from the server:
+    // take the server's gotQueries.patch as the got patch to emit (replacing
+    // local synthesis), and clear the acked prefix of the shipped desired delta
+    // once the server acks that version (the ack never leads its row effects —
+    // invariant 13 — so the client marks a query got only after its rows land).
+    function applyServerGotQueries(response) {
+      var got = response.gotQueries;
+      this.pendingGotQueriesPatch = got ? got.patch : [];
+      if (got && this.sentQueryVersion !== void 0 && got.version >= this.sentQueryVersion) {
+        this.desiredQueryPatch.splice(0, this.sentQueryPatchLen);
+        this.sentQueryVersion = void 0;
+      }
+    }
   }, {
     key: "answerMutationRecoveryPull",
     value: async function answerMutationRecoveryPull(body) {
-      var response = await this.fetchPull(body.clientGroupID, body.cookie);
+      var response = await this.fetchPull(body.clientGroupID, body.cookie, false);
       var cookie = toWebSocketCookie(response.cookie);
       var _ref;
       this.emitMessage(["pull", {
@@ -448,12 +596,23 @@ var ZeroHttpSocket = /* @__PURE__ */function () {
     }
   }, {
     key: "fetchPull",
-    value: async function fetchPull(clientGroupID, cookie) {
-      return await this.postJSON("/pull", {
+    value: async function fetchPull(clientGroupID, cookie, includeQueries) {
+      var body = {
         clientID: this.clientID,
         clientGroupID,
         cookie: toHttpCookie(cookie)
-      });
+      };
+      if (includeQueries && this.state.queryAware && this.desiredQueryPatch.length > 0) {
+        this.sentQueryVersion = this.queryVersion;
+        this.sentQueryPatchLen = this.desiredQueryPatch.length;
+        body.queries = {
+          version: this.queryVersion,
+          patch: [...this.desiredQueryPatch]
+        };
+      } else {
+        this.sentQueryVersion = void 0;
+      }
+      return await this.postJSON("/pull", body);
     }
   }, {
     key: "postJSON",
@@ -511,9 +670,14 @@ var ZeroHttpSocket = /* @__PURE__ */function () {
   }, {
     key: "emitPoke",
     value: function emitPoke(response) {
-      var nextCookie = toWebSocketCookie(response.cookie);
-      if (isStaleCookie(this.cookie, response.cookie)) {
+      var currentServer = toHttpCookie(this.cookie);
+      var nextCookie;
+      if (currentServer !== null && response.cookie < currentServer) {
         throw new Error(`zero-http pull returned stale cookie ${response.cookie} for ${this.cookie}`);
+      } else if (currentServer !== null && response.cookie === currentServer) {
+        nextCookie = toLocalWebSocketCookie(response.cookie, ++this.nextLocalCookieID);
+      } else {
+        nextCookie = toWebSocketCookie(response.cookie);
       }
       var pokeID = `zero-http-${++this.state.nextPokeID}`;
       var gotQueries = this.pendingGotQueriesPatch;
@@ -688,10 +852,6 @@ function toWebSocketCookie(cookie) {
 function toLocalWebSocketCookie(cookie, localID) {
   return `${String(cookie).padStart(COOKIE_WIDTH, "0")}#${String(localID).padStart(6, "0")}`;
 }
-function isStaleCookie(current, next) {
-  var currentNumber = toHttpCookie(current);
-  return currentNumber !== null && next <= currentNumber;
-}
 function errorMessage(error) {
   return _instanceof(error, Error) ? error.message : String(error);
 }