@liveblocks/core 1.1.0-test1 → 1.1.0

package/dist/index.d.ts

@@ -636,14 +636,34 @@ declare enum WebsocketCloseCodes {
     CLOSE_WITHOUT_RETRY = 4999
 }
 
+/**
+ * Old connection statuses, here for backward-compatibility reasons only.
+ */
+declare type LegacyConnectionStatus = "closed" | "authenticating" | "connecting" | "open" | "unavailable" | "failed";
+/**
+ * Returns a human-readable status indicating the current connection status of
+ * a Room, as returned by `room.getStatus()`. Can be used to implement
+ * a connection status badge.
+ */
+declare type Status = "initial" | "connecting" | "connected" | "reconnecting" | "disconnected";
+/**
+ * Used to report about app-level reconnection issues.
+ *
+ * Normal (quick) reconnects won't be reported as a "lost connection". Instead,
+ * the application will only get an event if the reconnection attempts by the
+ * client are taking (much) longer than usual. Definitely a situation you want
+ * to inform your users about, for example, by throwing a toast message on
+ * screen, or show a "trying to reconnect" banner.
+ */
+declare type LostConnectionEvent = "lost" | "restored" | "failed";
 /**
  * Arbitrary record that will be used as the authentication "token". It's the
  * value that is returned by calling the authentication delegate, and will get
  * passed to the connection factory delegate. This value will be remembered by
  * the connection manager, but its value will not be interpreted, so it can be
- * any object value.
+ * any value (except null).
  */
-declare type BaseAuthResult = Record<string, unknown>;
+declare type BaseAuthResult = NonNullable<Json>;
 declare type Delegates<T extends BaseAuthResult> = {
     authenticate: () => Promise<T>;
     createSocket: (token: T) => IWebSocketInstance;
@@ -735,28 +755,6 @@ declare type CustomEvent<TRoomEvent extends Json> = {
     connectionId: number;
     event: TRoomEvent;
 };
-declare type Connection = {
-    status: "closed";
-} | {
-    status: "authenticating";
-} | {
-    status: "connecting";
-    id: number;
-    userId?: string;
-    userInfo?: Json;
-    isReadOnly: boolean;
-} | {
-    status: "open";
-    id: number;
-    userId?: string;
-    userInfo?: Json;
-    isReadOnly: boolean;
-} | {
-    status: "unavailable";
-} | {
-    status: "failed";
-};
-declare type ConnectionStatus = Connection["status"];
 declare type StorageStatus = "not-loaded" | "loading" | "synchronizing" | "synchronized";
 interface History {
     /**
@@ -893,12 +891,47 @@ declare type SubscribeFn<TPresence extends JsonObject, _TStorage extends LsonObj
      */
     (type: "error", listener: ErrorCallback): () => void;
     /**
-     * Subscribe to connection state updates.
+     * @deprecated This API will be removed in a future version of Liveblocks.
+     * Prefer using the newer `.subscribe('status')` API.
+     *
+     * We recommend making the following changes if you use these APIs:
+     *
+     *     OLD APIs                       NEW APIs
+     *     .getConnectionState()     -->  .getStatus()
+     *     .subscribe('connection')  -->  .subscribe('status')
+     *
+     *     OLD STATUSES         NEW STATUSES
+     *     closed          -->  initial
+     *     authenticating  -->  connecting
+     *     connecting      -->  connecting
+     *     open            -->  connected
+     *     unavailable     -->  reconnecting
+     *     failed          -->  disconnected
+     *
+     * Subscribe to legacy connection status updates.
+     *
+     * @returns Unsubscribe function.
+     *
+     */
+    (type: "connection", listener: Callback<LegacyConnectionStatus>): () => void;
+    /**
+     * Subscribe to connection status updates. The callback will be called any
+     * time the status changes.
      *
      * @returns Unsubscribe function.
      *
      */
-    (type: "connection", listener: Callback<ConnectionStatus>): () => void;
+    (type: "status", listener: Callback<Status>): () => void;
+    /**
+     * Subscribe to the exceptional event where reconnecting to the Liveblocks
+     * servers is taking longer than usual. This typically is a sign of a client
+     * that has lost internet connectivity.
+     *
+     * This isn't problematic (because the Liveblocks client is still trying to
+     * reconnect), but it's typically a good idea to inform users about it if
+     * the connection takes too long to recover.
+     */
+    (type: "lost-connection", listener: Callback<LostConnectionEvent>): () => void;
     /**
      * Subscribes to changes made on a Live structure. Returns an unsubscribe function.
      * In a future version, we will also expose what exactly changed in the Live structure.
@@ -975,7 +1008,30 @@ declare type Room<TPresence extends JsonObject, TStorage extends LsonObject, TUs
      * metadata and connection ID (from the auth server).
      */
     isSelfAware(): boolean;
-    getConnectionState(): ConnectionStatus;
+    /**
+     * @deprecated This API will be removed in a future version of Liveblocks.
+     * Prefer using `.getStatus()` instead.
+     *
+     * We recommend making the following changes if you use these APIs:
+     *
+     *     OLD APIs                       NEW APIs
+     *     .getConnectionState()     -->  .getStatus()
+     *     .subscribe('connection')  -->  .subscribe('status')
+     *
+     *     OLD STATUSES         NEW STATUSES
+     *     closed          -->  initial
+     *     authenticating  -->  connecting
+     *     connecting      -->  connecting
+     *     open            -->  connected
+     *     unavailable     -->  reconnecting
+     *     failed          -->  disconnected
+     */
+    getConnectionState(): LegacyConnectionStatus;
+    /**
+     * Return the current connection status for this room. Can be used to display
+     * a status badge for your Liveblocks connection.
+     */
+    getStatus(): Status;
     readonly subscribe: SubscribeFn<TPresence, TStorage, TUserMeta, TRoomEvent>;
     /**
      * Room's history contains functions that let you undo and redo operation made on by the current client on the presence and storage.
@@ -1056,6 +1112,9 @@ declare type Room<TPresence extends JsonObject, TStorage extends LsonObject, TUs
      */
     getStorageSnapshot(): LiveObject<TStorage> | null;
     readonly events: {
+        readonly connection: Observable<LegacyConnectionStatus>;
+        readonly status: Observable<Status>;
+        readonly lostConnection: Observable<LostConnectionEvent>;
         readonly customEvent: Observable<{
             connectionId: number;
             event: TRoomEvent;
@@ -1066,12 +1125,12 @@ declare type Room<TPresence extends JsonObject, TStorage extends LsonObject, TUs
             event: OthersEvent<TPresence, TUserMeta>;
         }>;
         readonly error: Observable<Error>;
-        readonly connection: Observable<ConnectionStatus>;
         readonly storage: Observable<StorageUpdate[]>;
         readonly history: Observable<HistoryEvent>;
         /**
-         * Subscribe to the storage loaded event. Will fire at most once during the
-         * lifetime of a Room.
+         * Subscribe to the storage loaded event. Will fire any time a full Storage
+         * copy is downloaded. (This happens after the initial connect, and on
+         * every reconnect.)
          */
         readonly storageDidLoad: Observable<void>;
         readonly storageStatus: Observable<StorageStatus>;
@@ -1168,6 +1227,7 @@ declare type AuthEndpoint = string | ((room: string) => Promise<{
  */
 declare type ClientOptions = {
     throttle?: number;
+    lostConnectionTimeout?: number;
     polyfills?: Polyfills;
     unstable_fallbackToHTTP?: boolean;
     /**
@@ -1762,7 +1822,7 @@ declare type ClientToPanelMessage =
  | {
     msg: "room::sync::full";
     roomId: string;
-    status: ConnectionStatus;
+    status: Status;
     storage: readonly LsonTreeNode[] | null;
     me: UserTreeNode | null;
     others: readonly UserTreeNode[];
@@ -1773,7 +1833,7 @@ declare type ClientToPanelMessage =
  | {
     msg: "room::sync::partial";
     roomId: string;
-    status?: ConnectionStatus;
+    status?: Status;
     storage?: readonly LsonTreeNode[];
     me?: UserTreeNode;
     others?: readonly UserTreeNode[];
@@ -1824,4 +1884,4 @@ declare type EnsureJson<T> = [
     [K in keyof T]: EnsureJson<T[K]>;
 };
 
-export { AckOp, AppOnlyAuthToken, AuthToken, BaseAuthResult, BaseUserMeta, BroadcastEventClientMsg, BroadcastOptions, BroadcastedEventServerMsg, Client, ClientMsg, ClientMsgCode, ConnectionStatus, CrdtType, CreateChildOp, CreateListOp, CreateMapOp, CreateObjectOp, CreateOp, CreateRegisterOp, CreateRootObjectOp, Delegates, DeleteCrdtOp, DeleteObjectKeyOp, DevToolsTreeNode as DevTools, protocol as DevToolsMsg, EnsureJson, FetchStorageClientMsg, History, IWebSocket, IWebSocketCloseEvent, IWebSocketEvent, IWebSocketInstance, IWebSocketMessageEvent, IdTuple, Immutable, InitialDocumentStateServerMsg, Json, JsonArray, JsonObject, JsonScalar, LiveList, LiveListUpdate, LiveMap, LiveMapUpdate, LiveNode, LiveObject, LiveObjectUpdate, LiveStructure, Lson, LsonObject, NodeMap, Op, OpCode, Others, ParentToChildNodeMap, PlainLson, PlainLsonFields, PlainLsonList, PlainLsonMap, PlainLsonObject, RejectedStorageOpServerMsg, Resolve, Room, RoomAuthToken, RoomInitializers, RoomStateServerMsg, SerializedChild, SerializedCrdt, SerializedList, SerializedMap, SerializedObject, SerializedRegister, SerializedRootObject, ServerMsg, ServerMsgCode, SetParentKeyOp, StorageStatus, StorageUpdate, ToImmutable, ToJson, UpdateObjectOp, UpdatePresenceClientMsg, UpdatePresenceServerMsg, UpdateStorageClientMsg, UpdateStorageServerMsg, User, UserJoinServerMsg, UserLeftServerMsg, WebsocketCloseCodes, asArrayWithLegacyMethods, asPos, assert, assertNever, b64decode, createClient, deprecate, deprecateIf, errorIf, freeze, isAppOnlyAuthToken, isAuthToken, isChildCrdt, isJsonArray, isJsonObject, isJsonScalar, isPlainObject, isRoomAuthToken, isRootCrdt, legacy_patchImmutableObject, lsonToJson, makePosition, nn, patchLiveObjectKey, shallow, throwUsageError, toPlainLson, tryParseJson, withTimeout };
+export { AckOp, AppOnlyAuthToken, AuthToken, BaseAuthResult, BaseUserMeta, BroadcastEventClientMsg, BroadcastOptions, BroadcastedEventServerMsg, Client, ClientMsg, ClientMsgCode, CrdtType, CreateChildOp, CreateListOp, CreateMapOp, CreateObjectOp, CreateOp, CreateRegisterOp, CreateRootObjectOp, Delegates, DeleteCrdtOp, DeleteObjectKeyOp, DevToolsTreeNode as DevTools, protocol as DevToolsMsg, EnsureJson, FetchStorageClientMsg, History, IWebSocket, IWebSocketCloseEvent, IWebSocketEvent, IWebSocketInstance, IWebSocketMessageEvent, IdTuple, Immutable, InitialDocumentStateServerMsg, Json, JsonArray, JsonObject, JsonScalar, LegacyConnectionStatus, LiveList, LiveListUpdate, LiveMap, LiveMapUpdate, LiveNode, LiveObject, LiveObjectUpdate, LiveStructure, LostConnectionEvent, Lson, LsonObject, NodeMap, Op, OpCode, Others, ParentToChildNodeMap, PlainLson, PlainLsonFields, PlainLsonList, PlainLsonMap, PlainLsonObject, RejectedStorageOpServerMsg, Resolve, Room, RoomAuthToken, RoomInitializers, RoomStateServerMsg, SerializedChild, SerializedCrdt, SerializedList, SerializedMap, SerializedObject, SerializedRegister, SerializedRootObject, ServerMsg, ServerMsgCode, SetParentKeyOp, Status, StorageStatus, StorageUpdate, ToImmutable, ToJson, UpdateObjectOp, UpdatePresenceClientMsg, UpdatePresenceServerMsg, UpdateStorageClientMsg, UpdateStorageServerMsg, User, UserJoinServerMsg, UserLeftServerMsg, WebsocketCloseCodes, asArrayWithLegacyMethods, asPos, assert, assertNever, b64decode, createClient, deprecate, deprecateIf, errorIf, freeze, isAppOnlyAuthToken, isAuthToken, isChildCrdt, isJsonArray, isJsonObject, isJsonScalar, isPlainObject, isRoomAuthToken, isRootCrdt, legacy_patchImmutableObject, lsonToJson, makePosition, nn, patchLiveObjectKey, shallow, throwUsageError, toPlainLson, tryParseJson, withTimeout };

package/dist/index.js

@@ -157,7 +157,7 @@ var onMessageFromPanel = eventSource.observable;
 // src/devtools/index.ts
 var VERSION = true ? (
   /* istanbul ignore next */
-  "1.1.0-test1"
+  "1.1.0"
 ) : "dev";
 var _devtoolsSetupHasRun = false;
 function setupDevTools(getAllRooms) {
@@ -199,7 +199,7 @@ function startSyncStream(room) {
   fullSync(room);
   unsubsByRoomId.set(room.id, [
     // When the connection status changes
-    room.events.connection.subscribe(() => partialSyncConnection(room)),
+    room.events.status.subscribe(() => partialSyncConnection(room)),
     // When storage initializes, send the update
     room.events.storageDidLoad.subscribeOnce(() => partialSyncStorage(room)),
     // Any time storage updates, send the new storage root
@@ -213,7 +213,7 @@ function partialSyncConnection(room) {
   sendToPanel({
     msg: "room::sync::partial",
     roomId: room.id,
-    status: room.getConnectionState()
+    status: room.getStatus()
   });
 }
 function partialSyncStorage(room) {
@@ -254,7 +254,7 @@ function fullSync(room) {
   sendToPanel({
     msg: "room::sync::full",
     roomId: room.id,
-    status: room.getConnectionState(),
+    status: room.getStatus(),
     storage: (_a = root == null ? void 0 : root.toTreeNode("root").payload) != null ? _a : null,
     me,
     others
@@ -823,22 +823,37 @@ function withTimeout(promise, millis, errmsg = "Timed out") {
 }
 
 // src/connection.ts
-function toPublicConnectionStatus(state) {
+function newToLegacyStatus(status) {
+  switch (status) {
+    case "connecting":
+      return "connecting";
+    case "connected":
+      return "open";
+    case "reconnecting":
+      return "unavailable";
+    case "disconnected":
+      return "failed";
+    case "initial":
+      return "closed";
+    default:
+      return "closed";
+  }
+}
+function toNewConnectionStatus(machine) {
+  const state = machine.currentState;
   switch (state) {
     case "@ok.connected":
     case "@ok.awaiting-pong":
-      return "open";
+      return "connected";
     case "@idle.initial":
-      return "closed";
+      return "initial";
     case "@auth.busy":
     case "@auth.backoff":
-      return "authenticating";
     case "@connecting.busy":
-      return "connecting";
     case "@connecting.backoff":
-      return "unavailable";
+      return machine.context.successCount > 0 ? "reconnecting" : "connecting";
     case "@idle.failed":
-      return "failed";
+      return "disconnected";
     default:
       return assertNever(state, "Unknown state");
   }
@@ -873,6 +888,9 @@ function increaseBackoffDelayAggressively(context) {
     backoffDelay: nextBackoffDelay(context.backoffDelay, BACKOFF_DELAYS_SLOW)
   });
 }
+function resetSuccessCount(context) {
+  context.patch({ successCount: 0 });
+}
 function log(level, message) {
   const logger = level === 2 /* ERROR */ ? error : level === 1 /* WARN */ ? warn : (
     /* black hole */
@@ -883,9 +901,34 @@ function log(level, message) {
     logger(message);
   };
 }
-function sendHeartbeat(ctx) {
-  var _a;
-  (_a = ctx.socket) == null ? void 0 : _a.send("ping");
+function logPrematureErrorOrCloseEvent(e) {
+  const conn = "Connection to Liveblocks websocket server";
+  return (ctx) => {
+    if (e instanceof Error) {
+      warn(`${conn} could not be established. ${String(e)}`);
+    } else {
+      warn(
+        isCloseEvent(e) ? `${conn} closed prematurely (code: ${e.code}). Retrying in ${ctx.backoffDelay}ms.` : `${conn} could not be established.`
+      );
+    }
+  };
+}
+function logCloseEvent(event) {
+  return (ctx) => {
+    warn(
+      `Connection to Liveblocks websocket server closed (code: ${event.code}). Retrying in ${ctx.backoffDelay}ms.`
+    );
+  };
+}
+var logPermanentClose = log(
+  1 /* WARN */,
+  "Connection to WebSocket closed permanently. Won't retry."
+);
+function isCloseEvent(error2) {
+  return !(error2 instanceof Error) && error2.type === "close";
+}
+function isCustomCloseEvent(error2) {
+  return isCloseEvent(error2) && error2.code >= 4e3 && error2.code < 4100;
 }
 function enableTracing(machine) {
   const start = (/* @__PURE__ */ new Date()).getTime();
@@ -916,16 +959,18 @@ function defineConnectivityEvents(machine) {
   const statusDidChange = makeEventSource();
   const didConnect = makeEventSource();
   const didDisconnect = makeEventSource();
-  let oldPublicStatus = null;
-  const unsubscribe = machine.events.didEnterState.subscribe((newState) => {
-    const newPublicStatus = toPublicConnectionStatus(newState);
-    statusDidChange.notify(newPublicStatus);
-    if (oldPublicStatus === "open" && newPublicStatus !== "open") {
+  let lastStatus = null;
+  const unsubscribe = machine.events.didEnterState.subscribe(() => {
+    const currStatus = toNewConnectionStatus(machine);
+    if (currStatus !== lastStatus) {
+      statusDidChange.notify(currStatus);
+    }
+    if (lastStatus === "connected" && currStatus !== "connected") {
       didDisconnect.notify();
-    } else if (oldPublicStatus !== "open" && newPublicStatus === "open") {
+    } else if (lastStatus !== "connected" && currStatus === "connected") {
       didConnect.notify();
     }
-    oldPublicStatus = newPublicStatus;
+    lastStatus = currStatus;
   });
   return {
     statusDidChange: statusDidChange.observable,
@@ -940,6 +985,7 @@ function createConnectionStateMachine(delegates, enableDebugLogging) {
   onMessage.pause();
   const onLiveblocksError = makeEventSource();
   const initialContext = {
+    successCount: 0,
     token: null,
     socket: null,
     backoffDelay: RESET_DELAY
@@ -948,11 +994,11 @@ function createConnectionStateMachine(delegates, enableDebugLogging) {
   machine.addTransitions("*", {
     RECONNECT: {
       target: "@auth.backoff",
-      effect: increaseBackoffDelay
+      effect: [increaseBackoffDelay, resetSuccessCount]
     },
     DISCONNECT: "@idle.initial"
   });
-  machine.addTransitions("@idle.*", {
+  machine.onEnter("@idle.*", resetSuccessCount).addTransitions("@idle.*", {
     CONNECT: (_, ctx) => (
       // If we still have a known token, try to reconnect to the socket directly,
       // otherwise, try to obtain a new token
@@ -1097,41 +1143,41 @@ function createConnectionStateMachine(delegates, enableDebugLogging) {
           effect: log(2 /* ERROR */, err.message)
         };
       }
+      if (isCloseEvent(err) && err.code === 4999) {
+        return {
+          target: "@idle.failed",
+          effect: log(2 /* ERROR */, err.reason)
+        };
+      }
+      if (isCustomCloseEvent(err) && err.code !== 4001) {
+        return {
+          target: "@connecting.backoff",
+          effect: [
+            increaseBackoffDelayAggressively,
+            logPrematureErrorOrCloseEvent(err)
+          ]
+        };
+      }
       return {
         target: "@auth.backoff",
-        effect: [
-          // Increase the backoff delay conditionally
-          // TODO: This is ugly. DRY this up with the other code 40xx checks elsewhere.
-          !(err instanceof Error) && err.type === "close" && err.code >= 4e3 && err.code <= 4100 ? increaseBackoffDelayAggressively : increaseBackoffDelay,
-          // Produce a useful log message
-          (ctx) => {
-            if (err instanceof Error) {
-              warn(String(err));
-            } else {
-              warn(
-                err.type === "close" ? `Connection to Liveblocks websocket server closed prematurely (code: ${err.code}). Retrying in ${ctx.backoffDelay}ms.` : "Connection to Liveblocks websocket server could not be established."
-              );
-            }
-          }
-        ]
+        effect: [increaseBackoffDelay, logPrematureErrorOrCloseEvent(err)]
       };
     }
   );
-  machine.addTimedTransition("@ok.connected", HEARTBEAT_INTERVAL, {
+  const sendHeartbeat = {
     target: "@ok.awaiting-pong",
-    effect: sendHeartbeat
-  }).addTransitions("@ok.connected", {
-    WINDOW_GOT_FOCUS: { target: "@ok.awaiting-pong", effect: sendHeartbeat }
-  });
-  const noPongAction = {
-    target: "@connecting.busy",
-    // Log implicit connection loss and drop the current open socket
-    effect: log(
-      1 /* WARN */,
-      "Received no pong from server, assume implicit connection loss."
-    )
+    effect: (ctx) => {
+      var _a;
+      (_a = ctx.socket) == null ? void 0 : _a.send("ping");
+    }
   };
-  machine.onEnter("@ok.*", () => {
+  machine.addTimedTransition("@ok.connected", HEARTBEAT_INTERVAL, sendHeartbeat).addTransitions("@ok.connected", {
+    NAVIGATOR_OFFLINE: sendHeartbeat,
+    // 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
+  });
+  machine.onEnter("@ok.*", (ctx) => {
+    ctx.patch({ successCount: ctx.successCount + 1 });
     const timerID = setTimeout(
       // On the next tick, start delivering all messages that have already
       // been received, and continue synchronous delivery of all future
@@ -1139,13 +1185,20 @@ function createConnectionStateMachine(delegates, enableDebugLogging) {
       onMessage.unpause,
       0
     );
-    return (ctx) => {
-      teardownSocket(ctx.socket);
-      ctx.patch({ socket: null });
+    return (ctx2) => {
+      teardownSocket(ctx2.socket);
+      ctx2.patch({ socket: null });
       clearTimeout(timerID);
       onMessage.pause();
     };
-  }).addTimedTransition("@ok.awaiting-pong", PONG_TIMEOUT, noPongAction).addTransitions("@ok.awaiting-pong", { PONG_TIMEOUT: noPongAction }).addTransitions("@ok.awaiting-pong", { PONG: "@ok.connected" }).addTransitions("@ok.*", {
+  }).addTransitions("@ok.awaiting-pong", { PONG: "@ok.connected" }).addTimedTransition("@ok.awaiting-pong", PONG_TIMEOUT, {
+    target: "@connecting.busy",
+    // Log implicit connection loss and drop the current open socket
+    effect: log(
+      1 /* WARN */,
+      "Received no pong from server, assume implicit connection loss."
+    )
+  }).addTransitions("@ok.*", {
     // When a socket receives an error, this can cause the closing of the
     // socket, or not. So always check to see if the socket is still OPEN or
     // not. When still OPEN, don't transition.
@@ -1163,37 +1216,31 @@ function createConnectionStateMachine(delegates, enableDebugLogging) {
       if (e.event.code === 4999) {
         return {
           target: "@idle.failed",
-          effect: log(
-            1 /* WARN */,
-            "Connection to WebSocket closed permanently. Won't retry."
-          )
+          effect: logPermanentClose
+        };
+      }
+      if (e.event.code === 4001) {
+        return {
+          target: "@auth.backoff",
+          effect: [increaseBackoffDelay, logCloseEvent(e.event)]
         };
       }
-      if (e.event.code >= 4e3 && e.event.code <= 4100) {
+      if (isCustomCloseEvent(e.event)) {
         return {
           target: "@connecting.backoff",
           effect: [
             increaseBackoffDelayAggressively,
-            (ctx) => warn(
-              `Connection to Liveblocks websocket server closed (code: ${e.event.code}). Retrying in ${ctx.backoffDelay}ms.`
-            ),
-            (_, { event }) => {
-              if (event.code >= 4e3 && event.code <= 4100) {
-                const err = new LiveblocksError(event.reason, event.code);
-                onLiveblocksError.notify(err);
-              }
+            logCloseEvent(e.event),
+            () => {
+              const err = new LiveblocksError(e.event.reason, e.event.code);
+              onLiveblocksError.notify(err);
             }
           ]
         };
       }
       return {
         target: "@connecting.backoff",
-        effect: [
-          increaseBackoffDelay,
-          (ctx) => warn(
-            `Connection to Liveblocks websocket server closed (code: ${e.event.code}). Retrying in ${ctx.backoffDelay}ms.`
-          )
-        ]
+        effect: [increaseBackoffDelay, logCloseEvent(e.event)]
       };
     }
   });
@@ -1202,7 +1249,10 @@ function createConnectionStateMachine(delegates, enableDebugLogging) {
     const win = typeof window !== "undefined" ? window : void 0;
     const root = win != null ? win : doc;
     machine.onEnter("*", (ctx) => {
-      function onBackOnline() {
+      function onNetworkOffline() {
+        machine.send({ type: "NAVIGATOR_OFFLINE" });
+      }
+      function onNetworkBackOnline() {
         machine.send({ type: "NAVIGATOR_ONLINE" });
       }
       function onVisibilityChange() {
@@ -1210,11 +1260,13 @@ function createConnectionStateMachine(delegates, enableDebugLogging) {
           machine.send({ type: "WINDOW_GOT_FOCUS" });
         }
       }
-      win == null ? void 0 : win.addEventListener("online", onBackOnline);
+      win == null ? void 0 : win.addEventListener("online", onNetworkBackOnline);
+      win == null ? void 0 : win.addEventListener("offline", onNetworkOffline);
       root == null ? void 0 : root.addEventListener("visibilitychange", onVisibilityChange);
       return () => {
         root == null ? void 0 : root.removeEventListener("visibilitychange", onVisibilityChange);
-        win == null ? void 0 : win.removeEventListener("online", onBackOnline);
+        win == null ? void 0 : win.removeEventListener("online", onNetworkBackOnline);
+        win == null ? void 0 : win.removeEventListener("offline", onNetworkOffline);
         teardownSocket(ctx.socket);
       };
     });
@@ -1249,22 +1301,21 @@ var ManagedSocket = class {
     this.events = events;
     this.cleanups = cleanups;
   }
-  get status() {
+  getLegacyStatus() {
+    return newToLegacyStatus(this.getStatus());
+  }
+  getStatus() {
     try {
-      return toPublicConnectionStatus(this.machine.currentState);
+      return toNewConnectionStatus(this.machine);
     } catch (e) {
-      return "closed";
+      return "initial";
     }
   }
   /**
    * Returns the current auth token.
    */
   get token() {
-    const tok = this.machine.context.token;
-    if (tok === null) {
-      throw new Error("Unexpected null token here");
-    }
-    return tok;
+    return this.machine.context.token;
   }
   /**
    * Call this method to try to connect to a WebSocket. This only has an effect
@@ -4173,9 +4224,6 @@ function makeIdFactory(connectionId) {
   let count = 0;
   return () => `${connectionId}:${count++}`;
 }
-function isConnectionSelfAware(connection) {
-  return connection.status === "open" || connection.status === "connecting";
-}
 function userToTreeNode(key, user) {
   return {
     type: "User",
@@ -4204,7 +4252,6 @@ function createRoom(options, config) {
     config.enableDebugLogging
   );
   const context = {
-    lastConnectionId: null,
     buffer: {
       flushTimerID: void 0,
       lastFlushedAt: 0,
@@ -4218,7 +4265,7 @@ function createRoom(options, config) {
       messages: [],
       storageOperations: []
     },
-    connection: new ValueRef({ status: "closed" }),
+    sessionInfo: new ValueRef(null),
     me: new MeRef(initialPresence),
     others: new OthersRef(),
     initialStorage,
@@ -4238,55 +4285,78 @@ function createRoom(options, config) {
   };
   const doNotBatchUpdates = (cb) => cb();
   const batchUpdates = (_d = config.unstable_batchedUpdates) != null ? _d : doNotBatchUpdates;
+  let lastToken;
   function onStatusDidChange(newStatus) {
-    if (newStatus === "open" || newStatus === "connecting") {
-      context.connection.set({
-        status: newStatus,
-        id: managedSocket.token.parsed.actor,
-        userInfo: managedSocket.token.parsed.info,
-        userId: managedSocket.token.parsed.id,
-        isReadOnly: isStorageReadOnly(managedSocket.token.parsed.scopes)
+    var _a2;
+    const token = (_a2 = managedSocket.token) == null ? void 0 : _a2.parsed;
+    if (token !== void 0 && token !== lastToken) {
+      context.sessionInfo.set({
+        id: token.actor,
+        userInfo: token.info,
+        userId: token.id,
+        isReadOnly: isStorageReadOnly(token.scopes)
       });
-    } else {
-      context.connection.set({ status: newStatus });
+      lastToken = token;
     }
     batchUpdates(() => {
-      eventHub.connection.notify(newStatus);
+      eventHub.status.notify(newStatus);
+      eventHub.connection.notify(newToLegacyStatus(newStatus));
     });
   }
-  function onDidConnect() {
-    const conn = context.connection.current;
-    if (conn.status !== "open") {
-      throw new Error("Unexpected non-open state here");
-    }
-    if (context.lastConnectionId !== void 0) {
-      context.buffer.me = {
-        type: "full",
-        data: (
-          // Because state.me.current is a readonly object, we'll have to
-          // make a copy here. Otherwise, type errors happen later when
-          // "patching" my presence.
-          __spreadValues({}, context.me.current)
-        )
-      };
-      tryFlushing();
+  let _connectionLossTimerId;
+  let _hasLostConnection = false;
+  function handleConnectionLossEvent(newStatus) {
+    if (newStatus === "reconnecting") {
+      _connectionLossTimerId = setTimeout(() => {
+        batchUpdates(() => {
+          eventHub.lostConnection.notify("lost");
+          _hasLostConnection = true;
+          context.others.clearOthers();
+          notify({ others: [{ type: "reset" }] }, doNotBatchUpdates);
+        });
+      }, config.lostConnectionTimeout);
+    } else {
+      clearTimeout(_connectionLossTimerId);
+      if (_hasLostConnection) {
+        if (newStatus === "disconnected") {
+          batchUpdates(() => {
+            eventHub.lostConnection.notify("failed");
+          });
+        } else {
+          batchUpdates(() => {
+            eventHub.lostConnection.notify("restored");
+          });
+        }
+        _hasLostConnection = false;
+      }
     }
-    context.lastConnectionId = conn.id;
-    context.idFactory = makeIdFactory(conn.id);
-    if (context.root) {
-      context.buffer.messages.push({ type: 200 /* FETCH_STORAGE */ });
+  }
+  function onDidConnect() {
+    const sessionInfo = context.sessionInfo.current;
+    if (sessionInfo === null) {
+      throw new Error("Unexpected missing session info");
+    }
+    context.buffer.me = {
+      type: "full",
+      data: (
+        // Because context.me.current is a readonly object, we'll have to
+        // make a copy here. Otherwise, type errors happen later when
+        // "patching" my presence.
+        __spreadValues({}, context.me.current)
+      )
+    };
+    context.idFactory = makeIdFactory(sessionInfo.id);
+    if (_getStorage$ !== null) {
+      refreshStorage({ flush: false });
     }
-    tryFlushing();
+    flushNowOrSoon();
   }
   function onDidDisconnect() {
     clearTimeout(context.buffer.flushTimerID);
-    batchUpdates(() => {
-      context.others.clearOthers();
-      notify({ others: [{ type: "reset" }] }, doNotBatchUpdates);
-    });
   }
   managedSocket.events.onMessage.subscribe(handleServerMessage);
   managedSocket.events.statusDidChange.subscribe(onStatusDidChange);
+  managedSocket.events.statusDidChange.subscribe(handleConnectionLossEvent);
   managedSocket.events.didConnect.subscribe(onDidConnect);
   managedSocket.events.didDisconnect.subscribe(onDidDisconnect);
   managedSocket.events.onLiveblocksError.subscribe((err) => {
@@ -4340,7 +4410,8 @@ function createRoom(options, config) {
       }
     },
     assertStorageIsWritable: () => {
-      if (isConnectionSelfAware(context.connection.current) && context.connection.current.isReadOnly) {
+      var _a2;
+      if ((_a2 = context.sessionInfo.current) == null ? void 0 : _a2.isReadOnly) {
         throw new Error(
           "Cannot write to storage with a read only user, please ensure the user has write permissions"
         );
@@ -4348,22 +4419,26 @@ function createRoom(options, config) {
     }
   };
   const eventHub = {
+    connection: makeEventSource(),
+    // Old/deprecated API
+    status: makeEventSource(),
+    // New/recommended API
+    lostConnection: makeEventSource(),
     customEvent: makeEventSource(),
     me: makeEventSource(),
     others: makeEventSource(),
     error: makeEventSource(),
-    connection: makeEventSource(),
     storage: makeEventSource(),
     history: makeEventSource(),
     storageDidLoad: makeEventSource(),
     storageStatus: makeEventSource()
   };
   function sendMessages(messageOrMessages) {
-    var _a2;
+    var _a2, _b2;
     const message = JSON.stringify(messageOrMessages);
     if (config.unstable_fallbackToHTTP) {
       const size = new TextEncoder().encode(message).length;
-      if (size > MAX_MESSAGE_SIZE && managedSocket.token.raw && config.httpSendEndpoint) {
+      if (size > MAX_MESSAGE_SIZE && ((_a2 = managedSocket.token) == null ? void 0 : _a2.raw) && config.httpSendEndpoint) {
         if (isTokenExpired(managedSocket.token.parsed)) {
           return managedSocket.reconnect();
         }
@@ -4371,7 +4446,7 @@ function createRoom(options, config) {
           message,
           managedSocket.token.raw,
           config.httpSendEndpoint,
-          (_a2 = config.polyfills) == null ? void 0 : _a2.fetch
+          (_b2 = config.polyfills) == null ? void 0 : _b2.fetch
         );
         warn(
           "Message was too large for websockets and sent over HTTP instead"
@@ -4382,15 +4457,17 @@ function createRoom(options, config) {
     managedSocket.send(message);
   }
   const self = new DerivedRef(
-    context.connection,
+    context.sessionInfo,
     context.me,
-    (conn, me) => isConnectionSelfAware(conn) ? {
-      connectionId: conn.id,
-      id: conn.userId,
-      info: conn.userInfo,
-      presence: me,
-      isReadOnly: conn.isReadOnly
-    } : null
+    (info, me) => {
+      return info !== null ? {
+        connectionId: info.id,
+        id: info.userId,
+        info: info.userInfo,
+        presence: me,
+        isReadOnly: info.isReadOnly
+      } : null;
+    }
   );
   const selfAsTreeNode = new DerivedRef(
     self,
@@ -4400,7 +4477,7 @@ function createRoom(options, config) {
     if (message.items.length === 0) {
       throw new Error("Internal error: cannot load storage without items");
     }
-    if (context.root) {
+    if (context.root !== void 0) {
       updateRoot(message.items, batchedUpdatesWrapper);
     } else {
       context.root = LiveObject._fromItems(message.items, pool);
@@ -4412,7 +4489,7 @@ function createRoom(options, config) {
     }
   }
   function updateRoot(items, batchedUpdatesWrapper) {
-    if (!context.root) {
+    if (context.root === void 0) {
       return;
     }
     const currentItems = /* @__PURE__ */ new Map();
@@ -4459,11 +4536,9 @@ function createRoom(options, config) {
     });
   }
   function getConnectionId() {
-    const conn = context.connection.current;
-    if (isConnectionSelfAware(conn)) {
-      return conn.id;
-    } else if (context.lastConnectionId !== null) {
-      return context.lastConnectionId;
+    const info = context.sessionInfo.current;
+    if (info) {
+      return info.id;
     }
     throw new Error(
       "Internal. Tried to get connection id but connection was never open"
@@ -4612,7 +4687,7 @@ function createRoom(options, config) {
       }
       context.activeBatch.updates.presence = true;
     } else {
-      tryFlushing();
+      flushNowOrSoon();
       batchUpdates(() => {
         if (options2 == null ? void 0 : options2.addToHistory) {
           addToUndoStack(
@@ -4699,7 +4774,7 @@ function createRoom(options, config) {
       data: context.me.current,
       targetActor: message.actor
     });
-    tryFlushing();
+    flushNowOrSoon();
     const user = context.others.getUser(message.actor);
     return user ? { type: "enter", user } : void 0;
   }
@@ -4785,9 +4860,7 @@ function createRoom(options, config) {
             const unacknowledgedOps = new Map(context.unacknowledgedOps);
             createOrUpdateRootFromMessage(message, doNotBatchUpdates);
             applyAndSendOps(unacknowledgedOps, doNotBatchUpdates);
-            if (_getInitialStateResolver !== null) {
-              _getInitialStateResolver();
-            }
+            _resolveStoragePromise == null ? void 0 : _resolveStoragePromise();
             notifyStorageStatus();
             eventHub.storageDidLoad.notify();
             break;
@@ -4834,7 +4907,7 @@ ${Array.from(traces).join("\n\n")}`
       notify(updates, doNotBatchUpdates);
     });
   }
-  function tryFlushing() {
+  function flushNowOrSoon() {
     const storageOps = context.buffer.storageOperations;
     if (storageOps.length > 0) {
       for (const op of storageOps) {
@@ -4842,7 +4915,7 @@ ${Array.from(traces).join("\n\n")}`
       }
       notifyStorageStatus();
     }
-    if (managedSocket.status !== "open") {
+    if (managedSocket.getStatus() !== "connected") {
       context.buffer.storageOperations = [];
       return;
     }
@@ -4864,7 +4937,7 @@ ${Array.from(traces).join("\n\n")}`
     } else {
       clearTimeout(context.buffer.flushTimerID);
       context.buffer.flushTimerID = setTimeout(
-        tryFlushing,
+        flushNowOrSoon,
         config.throttleDelay - elapsedMillis
       );
     }
@@ -4900,31 +4973,39 @@ ${Array.from(traces).join("\n\n")}`
   function broadcastEvent(event, options2 = {
     shouldQueueEventIfNotReady: false
   }) {
-    if (managedSocket.status !== "open" && !options2.shouldQueueEventIfNotReady) {
+    if (managedSocket.getStatus() !== "connected" && !options2.shouldQueueEventIfNotReady) {
       return;
     }
     context.buffer.messages.push({
       type: 103 /* BROADCAST_EVENT */,
       event
     });
-    tryFlushing();
+    flushNowOrSoon();
   }
   function dispatchOps(ops) {
     context.buffer.storageOperations.push(...ops);
-    tryFlushing();
+    flushNowOrSoon();
+  }
+  let _getStorage$ = null;
+  let _resolveStoragePromise = null;
+  function refreshStorage(options2) {
+    const messages = context.buffer.messages;
+    if (!messages.some((msg) => msg.type === 200 /* FETCH_STORAGE */)) {
+      messages.push({ type: 200 /* FETCH_STORAGE */ });
+    }
+    if (options2.flush) {
+      flushNowOrSoon();
+    }
   }
-  let _getInitialStatePromise = null;
-  let _getInitialStateResolver = null;
   function startLoadingStorage() {
-    if (_getInitialStatePromise === null) {
-      context.buffer.messages.push({ type: 200 /* FETCH_STORAGE */ });
-      tryFlushing();
-      _getInitialStatePromise = new Promise(
-        (resolve) => _getInitialStateResolver = resolve
-      );
+    if (_getStorage$ === null) {
+      refreshStorage({ flush: true });
+      _getStorage$ = new Promise((resolve) => {
+        _resolveStoragePromise = resolve;
+      });
       notifyStorageStatus();
     }
-    return _getInitialStatePromise;
+    return _getStorage$;
   }
   function getStorageSnapshot() {
     const root = context.root;
@@ -4937,7 +5018,7 @@ ${Array.from(traces).join("\n\n")}`
   }
   function getStorage() {
     return __async(this, null, function* () {
-      if (context.root) {
+      if (context.root !== void 0) {
         return Promise.resolve({
           root: context.root
         });
@@ -4968,7 +5049,7 @@ ${Array.from(traces).join("\n\n")}`
         context.buffer.storageOperations.push(op);
       }
     }
-    tryFlushing();
+    flushNowOrSoon();
   }
   function redo() {
     if (context.activeBatch) {
@@ -4990,7 +5071,7 @@ ${Array.from(traces).join("\n\n")}`
         context.buffer.storageOperations.push(op);
       }
     }
-    tryFlushing();
+    flushNowOrSoon();
   }
   function batch(callback) {
     if (context.activeBatch) {
@@ -5022,7 +5103,7 @@ ${Array.from(traces).join("\n\n")}`
           dispatchOps(currentBatch.ops);
         }
         notify(currentBatch.updates, doNotBatchUpdates);
-        tryFlushing();
+        flushNowOrSoon();
       }
     });
     return returnValue;
@@ -5038,13 +5119,11 @@ ${Array.from(traces).join("\n\n")}`
     }
   }
   function getStorageStatus() {
-    if (_getInitialStatePromise === null) {
-      return "not-loaded";
-    }
     if (context.root === void 0) {
-      return "loading";
+      return _getStorage$ === null ? "not-loaded" : "loading";
+    } else {
+      return context.unacknowledgedOps.size === 0 ? "synchronized" : "synchronizing";
     }
-    return context.unacknowledgedOps.size === 0 ? "synchronized" : "synchronizing";
   }
   let _lastStorageStatus = getStorageStatus();
   function notifyStorageStatus() {
@@ -5059,11 +5138,15 @@ ${Array.from(traces).join("\n\n")}`
     (others) => others.map((other, index) => userToTreeNode(`Other ${index}`, other))
   );
   const events = {
+    connection: eventHub.connection.observable,
+    // Old/deprecated API
+    status: eventHub.status.observable,
+    // New/recommended API
+    lostConnection: eventHub.lostConnection.observable,
     customEvent: eventHub.customEvent.observable,
     others: eventHub.others.observable,
     me: eventHub.me.observable,
     error: eventHub.error.observable,
-    connection: eventHub.connection.observable,
     storage: eventHub.storage.observable,
     history: eventHub.history.observable,
     storageDidLoad: eventHub.storageDidLoad.observable,
@@ -5091,7 +5174,7 @@ ${Array.from(traces).join("\n\n")}`
       send: {
         // These exist only for our E2E testing app
         explicitClose: (event) => managedSocket._privateSendMachineEvent({ type: "EXPLICIT_SOCKET_CLOSE", event }),
-        implicitClose: () => managedSocket._privateSendMachineEvent({ type: "PONG_TIMEOUT" })
+        implicitClose: () => managedSocket._privateSendMachineEvent({ type: "NAVIGATOR_OFFLINE" })
       }
     },
     id: config.roomId,
@@ -5118,8 +5201,9 @@ ${Array.from(traces).join("\n\n")}`
     getStorageStatus,
     events,
     // Core
-    getConnectionState: () => context.connection.current.status,
-    isSelfAware: () => isConnectionSelfAware(context.connection.current),
+    getStatus: () => managedSocket.getStatus(),
+    getConnectionState: () => managedSocket.getLegacyStatus(),
+    isSelfAware: () => context.sessionInfo.current !== null,
     getSelf: () => self.current,
     // Presence
     getPresence: () => context.me.current,
@@ -5171,6 +5255,12 @@ function makeClassicSubscribeFn(events) {
           return events.connection.subscribe(
             callback
           );
+        case "status":
+          return events.status.subscribe(callback);
+        case "lost-connection":
+          return events.lostConnection.subscribe(
+            callback
+          );
         case "history":
           return events.history.subscribe(callback);
         case "storage-status":
@@ -5204,7 +5294,7 @@ function makeClassicSubscribeFn(events) {
   return subscribe;
 }
 function isRoomEventName(value) {
-  return value === "my-presence" || value === "others" || value === "event" || value === "error" || value === "connection" || value === "history" || value === "storage-status";
+  return value === "my-presence" || value === "others" || value === "event" || value === "error" || value === "history" || value === "status" || value === "storage-status" || value === "lost-connection" || value === "connection";
 }
 function makeCreateSocketDelegateForRoom(liveblocksServer, WebSocketPolyfill) {
   return (richToken) => {
@@ -5221,7 +5311,7 @@ function makeCreateSocketDelegateForRoom(liveblocksServer, WebSocketPolyfill) {
       // @ts-ignore (__PACKAGE_VERSION__ will be injected by the build script)
       true ? (
         /* istanbul ignore next */
-        "1.1.0-test1"
+        "1.1.0"
       ) : "dev"}`
     );
   };
@@ -5324,20 +5414,28 @@ function fetchAuthEndpoint(fetch2, endpoint, body) {
 var MIN_THROTTLE = 16;
 var MAX_THROTTLE = 1e3;
 var DEFAULT_THROTTLE = 100;
+var MIN_LOST_CONNECTION_TIMEOUT = 200;
+var RECOMMENDED_MIN_LOST_CONNECTION_TIMEOUT = 1e3;
+var MAX_LOST_CONNECTION_TIMEOUT = 3e4;
+var DEFAULT_LOST_CONNECTION_TIMEOUT = 5e3;
 function getServerFromClientOptions(clientOptions) {
   const rawOptions = clientOptions;
   return typeof rawOptions.liveblocksServer === "string" ? rawOptions.liveblocksServer : "wss://api.liveblocks.io/v6";
 }
 function createClient(options) {
+  var _a, _b;
   const clientOptions = options;
-  const throttleDelay = getThrottleDelayFromOptions(clientOptions);
+  const throttleDelay = getThrottle((_a = clientOptions.throttle) != null ? _a : DEFAULT_THROTTLE);
+  const lostConnectionTimeout = getLostConnectionTimeout(
+    (_b = clientOptions.lostConnectionTimeout) != null ? _b : DEFAULT_LOST_CONNECTION_TIMEOUT
+  );
   const rooms = /* @__PURE__ */ new Map();
   function getRoom(roomId) {
     const room = rooms.get(roomId);
     return room ? room : null;
   }
   function enter(roomId, options2) {
-    var _a, _b, _c;
+    var _a2, _b2, _c;
     const existingRoom = rooms.get(roomId);
     if (existingRoom !== void 0) {
       return existingRoom;
@@ -5348,12 +5446,13 @@ function createClient(options) {
     );
     const newRoom = createRoom(
       {
-        initialPresence: (_a = options2.initialPresence) != null ? _a : {},
+        initialPresence: (_a2 = options2.initialPresence) != null ? _a2 : {},
         initialStorage: options2.initialStorage
       },
       {
         roomId,
         throttleDelay,
+        lostConnectionTimeout,
         polyfills: clientOptions.polyfills,
         delegates: clientOptions.mockedDelegates,
         enableDebugLogging: clientOptions.enableDebugLogging,
@@ -5370,7 +5469,7 @@ function createClient(options) {
     rooms.set(roomId, newRoom);
     setupDevTools(() => Array.from(rooms.keys()));
     linkDevTools(roomId, newRoom);
-    const shouldConnect = (_b = options2.shouldInitiallyConnect) != null ? _b : true;
+    const shouldConnect = (_b2 = options2.shouldInitiallyConnect) != null ? _b2 : true;
     if (shouldConnect) {
       if (typeof atob === "undefined") {
         if (((_c = clientOptions.polyfills) == null ? void 0 : _c.atob) === void 0) {
@@ -5398,16 +5497,25 @@ function createClient(options) {
     leave
   };
 }
-function getThrottleDelayFromOptions(options) {
-  if (options.throttle === void 0) {
-    return DEFAULT_THROTTLE;
-  }
-  if (typeof options.throttle !== "number" || options.throttle < MIN_THROTTLE || options.throttle > MAX_THROTTLE) {
+function checkBounds(option, value, min, max, recommendedMin) {
+  if (typeof value !== "number" || value < min || value > max) {
     throw new Error(
-      `throttle should be a number between ${MIN_THROTTLE} and ${MAX_THROTTLE}.`
+      `${option} should be a number between ${recommendedMin != null ? recommendedMin : min} and ${max}.`
     );
   }
-  return options.throttle;
+  return value;
+}
+function getThrottle(value) {
+  return checkBounds("throttle", value, MIN_THROTTLE, MAX_THROTTLE);
+}
+function getLostConnectionTimeout(value) {
+  return checkBounds(
+    "lostConnectionTimeout",
+    value,
+    MIN_LOST_CONNECTION_TIMEOUT,
+    MAX_LOST_CONNECTION_TIMEOUT,
+    RECOMMENDED_MIN_LOST_CONNECTION_TIMEOUT
+  );
 }
 function prepareAuthentication(clientOptions, roomId) {
   const { publicApiKey, authEndpoint } = clientOptions;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@liveblocks/core",
-  "version": "1.1.0-test1",
+  "version": "1.1.0",
   "description": "Shared code and foundational internals for Liveblocks",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",