@liveblocks/react 0.18.0-beta3 → 0.18.0

package/.built-by-link-script

@@ -1 +1 @@
-ee7b9e79d3549611f64024b4247e9a862cfddd34
+ab4dc80c03188cfbc87c124cad9c824347a785b0

package/index.d.ts

@@ -39,7 +39,7 @@ declare type RoomProviderProps<TPresence extends JsonObject, TStorage extends Ls
  */
 declare type OmitFirstArg<F> = F extends (first: any, ...rest: infer A) => infer R ? (...args: A) => R : never;
 declare type MutationContext<TPresence extends JsonObject, TStorage extends LsonObject, TUserMeta extends BaseUserMeta> = {
-    root: LiveObject<TStorage>;
+    storage: LiveObject<TStorage>;
     self: User<TPresence, TUserMeta>;
     others: Others<TPresence, TUserMeta>;
     setMyPresence: (patch: Partial<TPresence>, options?: {
@@ -166,13 +166,6 @@ declare type RoomContextBundle<TPresence extends JsonObject, TStorage extends Ls
      * const [root] = useStorageRoot();
      */
     useStorageRoot(): [root: LiveObject<TStorage> | null];
-    /**
-     * Returns your entire Liveblocks Storage as an immutable data structure.
-     *
-     * @example
-     * const root = useStorage();
-     */
-    useStorage(): ToImmutable<TStorage> | null;
     /**
      * Extract arbitrary data from the Liveblocks Storage state, using an
      * arbitrary selector function.
@@ -192,7 +185,7 @@ declare type RoomContextBundle<TPresence extends JsonObject, TStorage extends Ls
      * return the result of a .map() or .filter() call from the selector. In
      * those cases, you'll probably want to use a `shallow` comparison check.
      */
-    useStorage<T>(selector: (root: ToImmutable<TStorage>) => T, isEqual?: (prev: T, curr: T) => boolean): T | null;
+    useStorage<T>(selector: (root: ToImmutable<TStorage>) => T, isEqual?: (prev: T | null, curr: T | null) => boolean): T | null;
     /**
      * Gets the current user once it is connected to the room.
      *
@@ -296,10 +289,10 @@ declare type RoomContextBundle<TPresence extends JsonObject, TStorage extends Ls
      * for each user in the room, e.g. cursors.
      *
      * @example
-     * const ids = useConnectionIds();
+     * const ids = useOthersConnectionIds();
      * // [2, 4, 7]
      */
-    useConnectionIds(): readonly number[];
+    useOthersConnectionIds(): readonly number[];
     /**
      * Related to useOthers(), but optimized for selecting only "subsets" of
      * others. This is useful for performance reasons in particular, because
@@ -307,11 +300,11 @@ declare type RoomContextBundle<TPresence extends JsonObject, TStorage extends Ls
      * re-renders that will be triggered.
      *
      * @example
-     * const avatars = useOthersWithData(user => user.info.avatar);
+     * const avatars = useOthersMapped(user => user.info.avatar);
      * //    ^^^^^^^
      * //    { connectionId: number; data: string }[]
      *
-     * The selector function you pass to useOthersWithData() is called an "item
+     * The selector function you pass to useOthersMapped() is called an "item
      * selector", and operates on a single user at a time. If you provide an
      * (optional) "item comparison" function, it will be used to compare each
      * item pairwise.
@@ -319,17 +312,14 @@ declare type RoomContextBundle<TPresence extends JsonObject, TStorage extends Ls
      * For example, to select multiple properties:
      *
      * @example
-     * const avatarsAndCursors = useOthersWithData(
+     * const avatarsAndCursors = useOthersMapped(
      *   user => [u.info.avatar, u.presence.cursor],
      *   shallow,  // 👈
      * );
      */
-    useOthersWithData<T>(itemSelector: (other: User<TPresence, TUserMeta>) => T, itemIsEqual?: (prev: T, curr: T) => boolean): readonly {
-        readonly connectionId: number;
-        readonly data: T;
-    }[];
+    useOthersMapped<T>(itemSelector: (other: User<TPresence, TUserMeta>) => T, itemIsEqual?: (prev: T, curr: T) => boolean): ReadonlyArray<readonly [connectionId: number, data: T]>;
     /**
-     * Given a connection ID (as obtained by using `useConnectionIds()`), you can
+     * Given a connection ID (as obtained by using `useOthersConnectionIds`), you can
      * call this selector deep down in your component stack to only have the
      * component re-render if properties for this particular user change.
      *
@@ -339,8 +329,8 @@ declare type RoomContextBundle<TPresence extends JsonObject, TStorage extends Ls
      */
     useOther(connectionId: number): User<TPresence, TUserMeta>;
     /**
-     * Given a connection ID (as obtained by using `useConnectionIds()`), you can
-     * call this selector deep down in your component stack to only have the
+     * Given a connection ID (as obtained by using `useOthersConnectionIds`), you
+     * can call this selector deep down in your component stack to only have the
      * component re-render if properties for this particular user change.
      *
      * @example
@@ -363,7 +353,7 @@ declare type RoomContextBundle<TPresence extends JsonObject, TStorage extends Ls
         addToHistory: boolean;
     }) => void;
     /**
-     * Create a callback function that can be called to mutate Liveblocks state.
+     * Create a callback function that lets you mutate Liveblocks state.
      *
      * The first argument that gets passed into your callback will be a "mutation
      * context", which exposes the following:
@@ -493,13 +483,6 @@ declare type RoomContextBundle<TPresence extends JsonObject, TStorage extends Ls
          * const [root] = useStorageRoot();
          */
         useStorageRoot(): [root: LiveObject<TStorage> | null];
-        /**
-         * Returns your entire Liveblocks Storage as an immutable data structure.
-         *
-         * @example
-         * const root = useStorage();
-         */
-        useStorage(): ToImmutable<TStorage>;
         /**
          * Extract arbitrary data from the Liveblocks Storage state, using an
          * arbitrary selector function.
@@ -623,10 +606,10 @@ declare type RoomContextBundle<TPresence extends JsonObject, TStorage extends Ls
          * for each user in the room, e.g. cursors.
          *
          * @example
-         * const ids = useConnectionIds();
+         * const ids = useOthersConnectionIds();
          * // [2, 4, 7]
          */
-        useConnectionIds(): readonly number[];
+        useOthersConnectionIds(): readonly number[];
         /**
          * Related to useOthers(), but optimized for selecting only "subsets" of
          * others. This is useful for performance reasons in particular, because
@@ -634,11 +617,11 @@ declare type RoomContextBundle<TPresence extends JsonObject, TStorage extends Ls
          * re-renders that will be triggered.
          *
          * @example
-         * const avatars = useOthersWithData(user => user.info.avatar);
+         * const avatars = useOthersMapped(user => user.info.avatar);
          * //    ^^^^^^^
          * //    { connectionId: number; data: string }[]
          *
-         * The selector function you pass to useOthersWithData() is called an "item
+         * The selector function you pass to useOthersMapped() is called an "item
          * selector", and operates on a single user at a time. If you provide an
          * (optional) "item comparison" function, it will be used to compare each
          * item pairwise.
@@ -646,19 +629,17 @@ declare type RoomContextBundle<TPresence extends JsonObject, TStorage extends Ls
          * For example, to select multiple properties:
          *
          * @example
-         * const avatarsAndCursors = useOthersWithData(
+         * const avatarsAndCursors = useOthersMapped(
          *   user => [u.info.avatar, u.presence.cursor],
          *   shallow,  // 👈
          * );
          */
-        useOthersWithData<T>(itemSelector: (other: User<TPresence, TUserMeta>) => T, itemIsEqual?: (prev: T, curr: T) => boolean): readonly {
-            readonly connectionId: number;
-            readonly data: T;
-        }[];
+        useOthersMapped<T>(itemSelector: (other: User<TPresence, TUserMeta>) => T, itemIsEqual?: (prev: T, curr: T) => boolean): ReadonlyArray<readonly [connectionId: number, data: T]>;
         /**
-         * Given a connection ID (as obtained by using `useConnectionIds()`), you
-         * can call this selector deep down in your component stack to only have
-         * the component re-render if properties for this particular user change.
+         * Given a connection ID (as obtained by using `useOthersConnectionIds`),
+         * you can call this selector deep down in your component stack to only
+         * have the component re-render if properties for this particular user
+         * change.
          *
          * @example
          * // Returns full user and re-renders whenever anything on the user changes
@@ -666,9 +647,10 @@ declare type RoomContextBundle<TPresence extends JsonObject, TStorage extends Ls
          */
         useOther(connectionId: number): User<TPresence, TUserMeta>;
         /**
-         * Given a connection ID (as obtained by using `useConnectionIds()`), you
-         * can call this selector deep down in your component stack to only have
-         * the component re-render if properties for this particular user change.
+         * Given a connection ID (as obtained by using `useOthersConnectionIds`),
+         * you can call this selector deep down in your component stack to only
+         * have the component re-render if properties for this particular user
+         * change.
          *
          * @example
          * // Returns only the selected values re-renders whenever that selection changes)
@@ -690,8 +672,7 @@ declare type RoomContextBundle<TPresence extends JsonObject, TStorage extends Ls
             addToHistory: boolean;
         }) => void;
         /**
-         * Create a callback function that can be called to mutate Liveblocks
-         * state.
+         * Create a callback function that lets you mutate Liveblocks state.
          *
          * The first argument that gets passed into your callback will be
          * a "mutation context", which exposes the following:

package/index.js

@@ -43,12 +43,12 @@ function getEmptyOthers() {
 function makeMutationContext(room) {
   const errmsg = "This mutation cannot be used until connected to the Liveblocks room";
   return {
-    get root() {
-      const root = room.getStorageSnapshot();
-      if (root === null) {
+    get storage() {
+      const mutableRoot = room.getStorageSnapshot();
+      if (mutableRoot === null) {
         throw new Error(errmsg);
       }
-      return root;
+      return mutableRoot;
     },
     get self() {
       const self = room.getSelf();
@@ -142,15 +142,14 @@ function createRoomContext(client) {
       isEqual
     );
   }
-  function useConnectionIds() {
+  function useOthersConnectionIds() {
     return useOthers(connectionIdSelector, _client.shallow);
   }
-  function useOthersWithData(itemSelector, itemIsEqual) {
+  function useOthersMapped(itemSelector, itemIsEqual) {
     const wrappedSelector = React2.useCallback(
-      (others) => others.map((other) => ({
-        connectionId: other.connectionId,
-        data: itemSelector(other)
-      })),
+      (others) => others.map(
+        (other) => [other.connectionId, itemSelector(other)]
+      ),
       [itemSelector]
     );
     const wrappedIsEqual = React2.useCallback(
@@ -158,7 +157,7 @@ function createRoomContext(client) {
         const eq = itemIsEqual != null ? itemIsEqual : Object.is;
         return a.length === b.length && a.every((atuple, index) => {
           const btuple = b[index];
-          return atuple.connectionId === btuple.connectionId && eq(atuple.data, btuple.data);
+          return atuple[0] === btuple[0] && eq(atuple[1], btuple[1]);
         });
       },
       [itemIsEqual]
@@ -346,10 +345,9 @@ function createRoomContext(client) {
       return root.get(key);
     }
   }
-  function useStorage(maybeSelector, isEqual) {
+  function useStorage(selector, isEqual) {
     const room = useRoom();
     const rootOrNull = useMutableStorageRoot();
-    const selector = maybeSelector != null ? maybeSelector : identity;
     const wrappedSelector = React2.useCallback(
       (rootOrNull2) => rootOrNull2 !== null ? selector(rootOrNull2) : null,
       [selector]
@@ -379,7 +377,7 @@ function createRoomContext(client) {
   function ensureNotServerSide() {
     if (typeof window === "undefined") {
       throw new Error(
-        "You cannot call the Suspense version of this hook on the server side. Make sure to only call them on the client side.\nFor tips for structuring your app, see XXX"
+        "You cannot use the Suspense version of this hook on the server side. Make sure to only call them on the client side.\nFor tips, see https://liveblocks.io/docs/api-reference/liveblocks-react#suspense-avoid-ssr"
       );
     }
   }
@@ -435,9 +433,13 @@ function createRoomContext(client) {
       isEqual
     );
   }
-  function useOthersWithDataSuspense(itemSelector, itemIsEqual) {
+  function useOthersConnectionIdsSuspense() {
+    useSuspendUntilPresenceLoaded();
+    return useOthersConnectionIds();
+  }
+  function useOthersMappedSuspense(itemSelector, itemIsEqual) {
     useSuspendUntilPresenceLoaded();
-    return useOthersWithData(itemSelector, itemIsEqual);
+    return useOthersMapped(itemSelector, itemIsEqual);
   }
   function useOtherSuspense(connectionId, selector, isEqual) {
     useSuspendUntilPresenceLoaded();
@@ -473,8 +475,8 @@ function createRoomContext(client) {
     useMyPresence,
     useUpdateMyPresence,
     useOthers,
-    useOthersWithData,
-    useConnectionIds,
+    useOthersMapped,
+    useOthersConnectionIds,
     useOther,
     useMutation,
     suspense: {
@@ -499,8 +501,8 @@ function createRoomContext(client) {
       useMyPresence,
       useUpdateMyPresence,
       useOthers: useOthersSuspense,
-      useOthersWithData: useOthersWithDataSuspense,
-      useConnectionIds,
+      useOthersMapped: useOthersMappedSuspense,
+      useOthersConnectionIds: useOthersConnectionIdsSuspense,
       useOther: useOtherSuspense,
       useMutation
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@liveblocks/react",
-  "version": "0.18.0-beta3",
+  "version": "0.18.0",
   "description": "A set of React hooks and providers to use Liveblocks declaratively.",
   "main": "./index.js",
   "module": "./index.mjs",
@@ -27,7 +27,7 @@
     "use-sync-external-store": "^1.2.0"
   },
   "peerDependencies": {
-    "@liveblocks/client": "0.18.0-beta3",
+    "@liveblocks/client": "0.18.0",
     "react": "^16.14.0 || ^17 || ^18"
   },
   "repository": {