@liveblocks/core 3.19.2 → 3.19.3

package/dist/index.cjs

@@ -6,7 +6,7 @@ var __export = (target, all) => {
 
 // src/version.ts
 var PKG_NAME = "@liveblocks/core";
-var PKG_VERSION = "3.19.2";
+var PKG_VERSION = "3.19.3";
 var PKG_FORMAT = "cjs";
 
 // src/dupe-detection.ts
@@ -2715,6 +2715,7 @@ var HttpClient = class {
 };
 
 // src/lib/fsm.ts
+var IGNORE = /* @__PURE__ */ Symbol("fsm.ignore");
 function distance(state1, state2) {
   if (state1 === state2) {
     return [0, 0];
@@ -2887,7 +2888,7 @@ var FSM = class {
     this.#eventHub = {
       didReceiveEvent: makeEventSource(),
       willTransition: makeEventSource(),
-      didIgnoreEvent: makeEventSource(),
+      didIgnoreUnexpectedEvent: makeEventSource(),
       willExitState: makeEventSource(),
       didEnterState: makeEventSource(),
       didExitState: makeEventSource()
@@ -2895,7 +2896,7 @@ var FSM = class {
     this.events = {
       didReceiveEvent: this.#eventHub.didReceiveEvent.observable,
       willTransition: this.#eventHub.willTransition.observable,
-      didIgnoreEvent: this.#eventHub.didIgnoreEvent.observable,
+      didIgnoreUnexpectedEvent: this.#eventHub.didIgnoreUnexpectedEvent.observable,
       willExitState: this.#eventHub.willExitState.observable,
       didEnterState: this.#eventHub.didEnterState.observable,
       didExitState: this.#eventHub.didExitState.observable
@@ -3018,9 +3019,14 @@ var FSM = class {
    * `context` params to conditionally decide which next state to transition
    * to.
    *
-   * If you set it to `null`, then the transition will be explicitly forbidden
-   * and throw an error. If you don't define a target for a transition, then
-   * such events will get ignored.
+   * If you don't define a target for a transition, the event is treated
+   * as unhandled in this state: `didIgnoreUnexpectedEvent` fires and the
+   * state does not change.
+   *
+   * To declare an event as an intentional silent no-op in this state, use
+   * the {@link IGNORE} sentinel — either statically (`{ EVENT: IGNORE }`)
+   * or as a return value from a target function. IGNORE'd events do not
+   * fire `didIgnoreUnexpectedEvent`.
    */
   addTransitions(nameOrPattern, mapping) {
     if (this.#runningState !== 0 /* NOT_STARTED_YET */) {
@@ -3040,7 +3046,12 @@ var FSM = class {
         }
         const target = target_;
         this.#knownEventTypes.add(type);
-        if (target !== void 0) {
+        if (target === void 0) {
+          continue;
+        }
+        if (target === IGNORE) {
+          map.set(type, IGNORE);
+        } else {
           const targetFn = typeof target === "function" ? target : () => target;
           map.set(type, targetFn);
         }
@@ -3139,12 +3150,14 @@ var FSM = class {
     if (this.#runningState === 2 /* STOPPED */) {
       return;
     }
-    const targetFn = this.#getTargetFn(event.type);
-    if (targetFn !== void 0) {
-      return this.#transition(event, targetFn);
-    } else {
-      this.#eventHub.didIgnoreEvent.notify(event);
+    const entry = this.#getTargetFn(event.type);
+    if (entry === IGNORE) {
+      return;
     }
+    if (entry !== void 0) {
+      return this.#transition(event, entry);
+    }
+    this.#eventHub.didIgnoreUnexpectedEvent.notify(event);
   }
   #transition(event, target) {
     this.#eventHub.didReceiveEvent.notify(event);
@@ -3153,8 +3166,7 @@ var FSM = class {
     const nextTarget = targetFn(event, this.#currentContext.current);
     let nextState;
     let effects = void 0;
-    if (nextTarget === null) {
-      this.#eventHub.didIgnoreEvent.notify(event);
+    if (nextTarget === IGNORE) {
       return;
     }
     if (typeof nextTarget === "string") {
@@ -3373,8 +3385,8 @@ function enableTracing(machine) {
     machine.events.didExitState.subscribe(
       ({ state, durationMs }) => log2(`Exited ${state} after ${durationMs.toFixed(0)}ms`)
     ),
-    machine.events.didIgnoreEvent.subscribe(
-      (e) => log2("Ignored event", e.type, e, "(current state won't handle it)")
+    machine.events.didIgnoreUnexpectedEvent.subscribe(
+      (e) => log2("Ignored unexpected event", e.type, e, "(no transition declared)")
     )
   ];
   return () => {
@@ -3486,7 +3498,12 @@ function createConnectionStateMachine(delegates, options) {
   );
   const onSocketError = (event) => machine.send({ type: "EXPLICIT_SOCKET_ERROR", event });
   const onSocketClose = (event) => machine.send({ type: "EXPLICIT_SOCKET_CLOSE", event });
-  const onSocketMessage = (event) => event.data === "pong" ? machine.send({ type: "PONG" }) : onMessage.notify(event);
+  const onSocketMessage = (event) => {
+    machine.send({ type: "ALIVE" });
+    if (event.data !== "pong") {
+      onMessage.notify(event);
+    }
+  };
   function teardownSocket(socket) {
     if (socket) {
       socket.removeEventListener("error", onSocketError);
@@ -3656,7 +3673,13 @@ function createConnectionStateMachine(delegates, options) {
         effect: [increaseBackoffDelay, logPrematureErrorOrCloseEvent(err)]
       };
     }
-  );
+  ).addTransitions("@connecting.busy", {
+    // The socket message listener is attached during @connecting.busy (see
+    // onEnterAsync above), so server frames (most notably the actor-id
+    // handshake) can fire onSocketMessage and emit a ALIVE before we
+    // reach @ok.*. That's fine. Heartbeat only matters in @ok.*.
+    ALIVE: IGNORE
+  });
   const sendHeartbeat = {
     target: "@ok.awaiting-pong",
     effect: (ctx) => {
@@ -3671,7 +3694,8 @@ function createConnectionStateMachine(delegates, options) {
   machine.addTimedTransition("@ok.connected", HEARTBEAT_INTERVAL, maybeHeartbeat).addTransitions("@ok.connected", {
     NAVIGATOR_OFFLINE: maybeHeartbeat,
     // Don't take the browser's word for it when it says it's offline. Do a ping/pong to make sure.
-    WINDOW_GOT_FOCUS: sendHeartbeat
+    WINDOW_GOT_FOCUS: sendHeartbeat,
+    ALIVE: IGNORE
   });
   machine.addTransitions("@idle.zombie", {
     WINDOW_GOT_FOCUS: "@connecting.backoff"
@@ -3692,7 +3716,7 @@ function createConnectionStateMachine(delegates, options) {
       clearTimeout(timerID);
       onMessage.pause();
     };
-  }).addTransitions("@ok.awaiting-pong", { PONG: "@ok.connected" }).addTimedTransition("@ok.awaiting-pong", PONG_TIMEOUT, {
+  }).addTransitions("@ok.awaiting-pong", { ALIVE: "@ok.connected" }).addTimedTransition("@ok.awaiting-pong", PONG_TIMEOUT, {
     target: "@connecting.busy",
     // Log implicit connection loss and drop the current open socket
     effect: log(
@@ -3705,7 +3729,7 @@ function createConnectionStateMachine(delegates, options) {
     // not. When still OPEN, don't transition.
     EXPLICIT_SOCKET_ERROR: (_, context) => {
       if (_optionalChain([context, 'access', _48 => _48.socket, 'optionalAccess', _49 => _49.readyState]) === 1) {
-        return null;
+        return IGNORE;
       }
       return {
         target: "@connecting.backoff",