@liveblocks/core 2.0.5 → 2.1.1-test1

package/dist/index.d.mts

@@ -31,6 +31,9 @@ declare type CustomAuthenticationResult = {
 declare type Json = JsonScalar | JsonArray | JsonObject;
 declare type JsonScalar = string | number | boolean | null;
 declare type JsonArray = Json[];
+/**
+ * Any valid JSON object.
+ */
 declare type JsonObject = {
     [key: string]: Json | undefined;
 };
@@ -1880,6 +1883,12 @@ declare type Room<P extends JsonObject = DP, S extends LsonObject = DS, U extend
      * const root = room.getStorageSnapshot();
      */
     getStorageSnapshot(): LiveObject<S> | null;
+    /**
+     * All possible room events, subscribable from a single place.
+     *
+     * @private These event sources are private for now, but will become public
+     * once they're stable.
+     */
     readonly events: {
         readonly status: Observable<Status>;
         readonly lostConnection: Observable<LostConnectionEvent>;
@@ -1888,7 +1897,12 @@ declare type Room<P extends JsonObject = DP, S extends LsonObject = DS, U extend
         readonly myPresence: Observable<P>;
         readonly others: Observable<OthersEvent<P, U>>;
         readonly error: Observable<LiveblocksError>;
+        /**
+         * @deprecated Renamed to `storageBatch`. The `storage` event source will
+         * soon be replaced by another/incompatible API.
+         */
         readonly storage: Observable<StorageUpdate[]>;
+        readonly storageBatch: Observable<StorageUpdate[]>;
         readonly history: Observable<HistoryEvent>;
         /**
          * Subscribe to the storage loaded event. Will fire any time a full Storage
@@ -1923,6 +1937,24 @@ declare type Room<P extends JsonObject = DP, S extends LsonObject = DS, U extend
      * - `synchronized`: Storage is in sync with Liveblocks servers.
      */
     getStorageStatus(): StorageStatus;
+    isPresenceReady(): boolean;
+    isStorageReady(): boolean;
+    /**
+     * Returns a Promise that resolves as soon as Presence is available, which
+     * happens shortly after the WebSocket connection has been established. Once
+     * this happens, `self` and `others` are known and available to use. After
+     * awaiting this promise, `.isPresenceReady()` will be guaranteed to be true.
+     * Even when calling this function multiple times, it's guaranteed to return
+     * the same Promise instance.
+     */
+    waitUntilPresenceReady(): Promise<void>;
+    /**
+     * Returns a Promise that resolves as soon as Storage has been loaded and
+     * available. After awaiting this promise, `.isStorageReady()` will be
+     * guaranteed to be true. Even when calling this function multiple times,
+     * it's guaranteed to return the same Promise instance.
+     */
+    waitUntilStorageReady(): Promise<void>;
     /**
      * Start an attempt to connect the room (aka "enter" it). Calling
      * `.connect()` only has an effect if the room is still in its idle initial

package/dist/index.d.ts

@@ -31,6 +31,9 @@ declare type CustomAuthenticationResult = {
 declare type Json = JsonScalar | JsonArray | JsonObject;
 declare type JsonScalar = string | number | boolean | null;
 declare type JsonArray = Json[];
+/**
+ * Any valid JSON object.
+ */
 declare type JsonObject = {
     [key: string]: Json | undefined;
 };
@@ -1880,6 +1883,12 @@ declare type Room<P extends JsonObject = DP, S extends LsonObject = DS, U extend
      * const root = room.getStorageSnapshot();
      */
     getStorageSnapshot(): LiveObject<S> | null;
+    /**
+     * All possible room events, subscribable from a single place.
+     *
+     * @private These event sources are private for now, but will become public
+     * once they're stable.
+     */
     readonly events: {
         readonly status: Observable<Status>;
         readonly lostConnection: Observable<LostConnectionEvent>;
@@ -1888,7 +1897,12 @@ declare type Room<P extends JsonObject = DP, S extends LsonObject = DS, U extend
         readonly myPresence: Observable<P>;
         readonly others: Observable<OthersEvent<P, U>>;
         readonly error: Observable<LiveblocksError>;
+        /**
+         * @deprecated Renamed to `storageBatch`. The `storage` event source will
+         * soon be replaced by another/incompatible API.
+         */
         readonly storage: Observable<StorageUpdate[]>;
+        readonly storageBatch: Observable<StorageUpdate[]>;
         readonly history: Observable<HistoryEvent>;
         /**
          * Subscribe to the storage loaded event. Will fire any time a full Storage
@@ -1923,6 +1937,24 @@ declare type Room<P extends JsonObject = DP, S extends LsonObject = DS, U extend
      * - `synchronized`: Storage is in sync with Liveblocks servers.
      */
     getStorageStatus(): StorageStatus;
+    isPresenceReady(): boolean;
+    isStorageReady(): boolean;
+    /**
+     * Returns a Promise that resolves as soon as Presence is available, which
+     * happens shortly after the WebSocket connection has been established. Once
+     * this happens, `self` and `others` are known and available to use. After
+     * awaiting this promise, `.isPresenceReady()` will be guaranteed to be true.
+     * Even when calling this function multiple times, it's guaranteed to return
+     * the same Promise instance.
+     */
+    waitUntilPresenceReady(): Promise<void>;
+    /**
+     * Returns a Promise that resolves as soon as Storage has been loaded and
+     * available. After awaiting this promise, `.isStorageReady()` will be
+     * guaranteed to be true. Even when calling this function multiple times,
+     * it's guaranteed to return the same Promise instance.
+     */
+    waitUntilStorageReady(): Promise<void>;
     /**
      * Start an attempt to connect the room (aka "enter" it). Calling
      * `.connect()` only has an effect if the room is still in its idle initial

package/dist/index.js

@@ -6,7 +6,7 @@ var __export = (target, all) => {
 
 // src/version.ts
 var PKG_NAME = "@liveblocks/core";
-var PKG_VERSION = "2.0.5";
+var PKG_VERSION = "2.1.1-test1";
 var PKG_FORMAT = "cjs";
 
 // src/dupe-detection.ts
@@ -72,14 +72,17 @@ function nn(value, errmsg = "Expected value to be non-nullable") {
 
 // src/lib/controlledPromise.ts
 function controlledPromise() {
-  let flagger;
-  const promise = new Promise((res) => {
-    flagger = res;
+  let resolve;
+  let reject;
+  const promise = new Promise((res, rej) => {
+    resolve = res;
+    reject = rej;
   });
-  if (!flagger) {
-    throw new Error("Should never happen");
-  }
-  return [promise, flagger];
+  return [promise, resolve, reject];
+}
+function Promise_withResolvers() {
+  const [promise, resolve, reject] = controlledPromise();
+  return { promise, resolve, reject };
 }
 
 // src/lib/EventSource.ts
@@ -634,6 +637,15 @@ async function withTimeout(promise, millis, errmsg) {
   });
   return Promise.race([promise, timer$]).finally(() => clearTimeout(timerID));
 }
+function memoize(factoryFn) {
+  let cached = null;
+  return () => {
+    if (cached === null) {
+      cached = { value: factoryFn() };
+    }
+    return cached.value;
+  };
+}
 
 // src/protocol/ServerMsg.ts
 var ServerMsgCode = /* @__PURE__ */ ((ServerMsgCode2) => {
@@ -1604,7 +1616,7 @@ function startSyncStream(room) {
     // When storage initializes, send the update
     room.events.storageDidLoad.subscribeOnce(() => partialSyncStorage(room)),
     // Any time storage updates, send the new storage root
-    room.events.storage.subscribe(() => partialSyncStorage(room)),
+    room.events.storageBatch.subscribe(() => partialSyncStorage(room)),
     // Any time "me" or "others" updates, send the new values accordingly
     room.events.self.subscribe(() => partialSyncMe(room)),
     room.events.others.subscribe(() => partialSyncOthers(room)),
@@ -5541,7 +5553,7 @@ function createRoom(options, config) {
     myPresence: makeEventSource(),
     others: makeEventSource(),
     error: makeEventSource(),
-    storage: makeEventSource(),
+    storageBatch: makeEventSource(),
     history: makeEventSource(),
     storageDidLoad: makeEventSource(),
     storageStatus: makeEventSource(),
@@ -5751,7 +5763,7 @@ function createRoom(options, config) {
       }
       if (storageUpdates !== void 0 && storageUpdates.size > 0) {
         const updates2 = Array.from(storageUpdates.values());
-        eventHub.storage.notify(updates2);
+        eventHub.storageBatch.notify(updates2);
       }
       notifyStorageStatus();
     });
@@ -6415,6 +6427,27 @@ ${Array.from(traces).join("\n\n")}`
       eventHub.storageStatus.notify(storageStatus);
     }
   }
+  function isPresenceReady() {
+    return self.current !== null;
+  }
+  async function waitUntilPresenceReady() {
+    while (!isPresenceReady()) {
+      const { promise, resolve } = Promise_withResolvers();
+      const unsub1 = events.self.subscribeOnce(resolve);
+      const unsub2 = events.status.subscribeOnce(resolve);
+      await promise;
+      unsub1();
+      unsub2();
+    }
+  }
+  function isStorageReady() {
+    return getStorageSnapshot() !== null;
+  }
+  async function waitUntilStorageReady() {
+    while (!isStorageReady()) {
+      await getStorage();
+    }
+  }
   const others_forDevTools = new DerivedRef(
     context.others,
     (others) => others.map((other, index) => userToTreeNode(`Other ${index}`, other))
@@ -6427,7 +6460,9 @@ ${Array.from(traces).join("\n\n")}`
     self: eventHub.self.observable,
     myPresence: eventHub.myPresence.observable,
     error: eventHub.error.observable,
-    storage: eventHub.storage.observable,
+    /** @deprecated */
+    storage: eventHub.storageBatch.observable,
+    storageBatch: eventHub.storageBatch.observable,
     history: eventHub.history.observable,
     storageDidLoad: eventHub.storageDidLoad.observable,
     storageStatus: eventHub.storageStatus.observable,
@@ -6578,6 +6613,10 @@ ${Array.from(traces).join("\n\n")}`
       getStorage,
       getStorageSnapshot,
       getStorageStatus,
+      isPresenceReady,
+      isStorageReady,
+      waitUntilPresenceReady: memoize(waitUntilPresenceReady),
+      waitUntilStorageReady: memoize(waitUntilStorageReady),
       events,
       // Core
       getStatus: () => managedSocket.getStatus(),
@@ -6594,7 +6633,7 @@ ${Array.from(traces).join("\n\n")}`
 }
 function makeClassicSubscribeFn(events) {
   function subscribeToLiveStructureDeeply(node, callback) {
-    return events.storage.subscribe((updates) => {
+    return events.storageBatch.subscribe((updates) => {
       const relatedUpdates = updates.filter(
         (update) => isSameNodeOrChildOf(update.node, node)
       );
@@ -6604,7 +6643,7 @@ function makeClassicSubscribeFn(events) {
     });
   }
   function subscribeToLiveStructureShallowly(node, callback) {
-    return events.storage.subscribe((updates) => {
+    return events.storageBatch.subscribe((updates) => {
       for (const update of updates) {
         if (update.node._id === node._id) {
           callback(update.node);
@@ -6656,7 +6695,7 @@ function makeClassicSubscribeFn(events) {
     if (second === void 0 || typeof first === "function") {
       if (typeof first === "function") {
         const storageCallback = first;
-        return events.storage.subscribe(storageCallback);
+        return events.storageBatch.subscribe(storageCallback);
       } else {
         throw new Error("Please specify a listener callback");
       }