@liveblocks/react 0.18.0-beta0 → 0.18.0-beta3

package/.built-by-link-script

@@ -1 +1 @@
-11a0666afa7ed3e5356b3c304466109fb37d8b87
+ee7b9e79d3549611f64024b4247e9a862cfddd34

package/index.d.ts

@@ -1,27 +1,57 @@
-import { JsonObject, LsonObject, LiveObject, BaseUserMeta, Json, Client, Room, BroadcastOptions, History, Others, User } from '@liveblocks/client';
-export { Json, JsonObject } from '@liveblocks/client';
+import { ReactElement, ReactNode } from 'react';
+import { JsonObject, LsonObject, BaseUserMeta, LiveObject, User, Others, Json, Room, BroadcastOptions, History, Client } from '@liveblocks/client';
+export { Json, JsonObject, shallow } from '@liveblocks/client';
 import { ToImmutable, Resolve, RoomInitializers } from '@liveblocks/client/internal';
-import * as React from 'react';
 
+declare type Props = {
+    fallback: NonNullable<ReactNode> | null;
+    children: () => ReactNode | undefined;
+};
+/**
+ * Almost like a normal <Suspense> component, except that for server-side
+ * renders, the fallback will be used.
+ *
+ * The child props will have to be provided in a function, i.e. change:
+ *
+ *   <Suspense fallback={<Loading />}>
+ *     <MyRealComponent a={1} />
+ *   </Suspense>
+ *
+ * To:
+ *
+ *   <ClientSideSuspense fallback={<Loading />}>
+ *     {() => <MyRealComponent a={1} />}
+ *   </ClientSideSuspense>
+ *
+ */
+declare function ClientSideSuspense(props: Props): ReactElement;
+
+declare type RoomProviderProps<TPresence extends JsonObject, TStorage extends LsonObject> = Resolve<{
+    /**
+     * The id of the room you want to connect to
+     */
+    id: string;
+    children: React.ReactNode;
+} & RoomInitializers<TPresence, TStorage>>;
 /**
  * For any function type, returns a similar function type, but without the
  * first argument.
  */
 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> = {
+declare type MutationContext<TPresence extends JsonObject, TStorage extends LsonObject, TUserMeta extends BaseUserMeta> = {
     root: LiveObject<TStorage>;
+    self: User<TPresence, TUserMeta>;
+    others: Others<TPresence, TUserMeta>;
     setMyPresence: (patch: Partial<TPresence>, options?: {
         addToHistory: boolean;
     }) => void;
 };
-declare type RoomProviderProps<TPresence extends JsonObject, TStorage extends LsonObject> = Resolve<{
+declare type RoomContextBundle<TPresence extends JsonObject, TStorage extends LsonObject, TUserMeta extends BaseUserMeta, TRoomEvent extends Json> = {
     /**
-     * The id of the room you want to connect to
+     * You normally don't need to directly interact with the RoomContext, but
+     * it can be necessary if you're building an advanced app where you need to
+     * set up a context bridge between two React renderers.
      */
-    id: string;
-    children: React.ReactNode;
-} & RoomInitializers<TPresence, TStorage>>;
-declare type RoomContextBundle<TPresence extends JsonObject, TStorage extends LsonObject, TUserMeta extends BaseUserMeta, TRoomEvent extends Json> = {
     RoomContext: React.Context<Room<TPresence, TStorage, TUserMeta, TRoomEvent> | null>;
     /**
      * Makes a Room available in the component hierarchy below.
@@ -29,13 +59,18 @@ declare type RoomContextBundle<TPresence extends JsonObject, TStorage extends Ls
      * That means that you can't have 2 RoomProvider with the same room id in your react tree.
      */
     RoomProvider(props: RoomProviderProps<TPresence, TStorage>): JSX.Element;
+    /**
+     * Returns the Room of the nearest RoomProvider above in the React component
+     * tree.
+     */
+    useRoom(): Room<TPresence, TStorage, TUserMeta, TRoomEvent>;
     /**
      * Returns a function that batches modifications made during the given function.
      * All the modifications are sent to other clients in a single message.
      * All the modifications are merged in a single history item (undo/redo).
      * All the subscribers are called only after the batch is over.
      */
-    useBatch(): (callback: () => void) => void;
+    useBatch<T>(): (callback: () => T) => T;
     /**
      * Returns a callback that lets you broadcast custom events to other users in the room
      *
@@ -123,6 +158,14 @@ declare type RoomContextBundle<TPresence extends JsonObject, TStorage extends Ls
      * const object = useObject("obj");
      */
     useObject<TKey extends Extract<keyof TStorage, string>>(key: TKey): TStorage[TKey] | null;
+    /**
+     * Returns the mutable (!) Storage root. This hook exists for
+     * backward-compatible reasons.
+     *
+     * @example
+     * const [root] = useStorageRoot();
+     */
+    useStorageRoot(): [root: LiveObject<TStorage> | null];
     /**
      * Returns your entire Liveblocks Storage as an immutable data structure.
      *
@@ -149,7 +192,39 @@ 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?: (a: T, b: T) => boolean): T | null;
+    useStorage<T>(selector: (root: ToImmutable<TStorage>) => T, isEqual?: (prev: T, curr: T) => boolean): T | null;
+    /**
+     * Gets the current user once it is connected to the room.
+     *
+     * @example
+     * const me = useSelf();
+     * const { x, y } = me.presence.cursor;
+     */
+    useSelf(): User<TPresence, TUserMeta> | null;
+    /**
+     * Extract arbitrary data based on the current user.
+     *
+     * The selector function will get re-evaluated any time your presence data
+     * changes.
+     *
+     * The component that uses this hook will automatically re-render if your
+     * selector function returns a different value from its previous run.
+     *
+     * By default `useSelf()` uses strict `===` to check for equality. Take extra
+     * care when returning a computed object or list, for example when you 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.
+     *
+     * Will return `null` while Liveblocks isn't connected to a room yet.
+     *
+     * @example
+     * const cursor = useSelf(me => me.presence.cursor);
+     * if (cursor !== null) {
+     *   const { x, y } = cursor;
+     * }
+     *
+     */
+    useSelf<T>(selector: (me: User<TPresence, TUserMeta>) => T, isEqual?: (prev: T, curr: T) => boolean): T | null;
     /**
      * Returns the presence of the current user of the current room, and a function to update it.
      * It is different from the setState function returned by the useState hook from React.
@@ -209,52 +284,70 @@ declare type RoomContextBundle<TPresence extends JsonObject, TStorage extends Ls
      * const someoneIsTyping = useOthers(users => users.some(u => u.presence.isTyping));
      *
      */
-    useOthers<T>(selector: (others: Others<TPresence, TUserMeta>) => T, isEqual?: (a: T, b: T) => boolean): T;
+    useOthers<T>(selector: (others: Others<TPresence, TUserMeta>) => T, isEqual?: (prev: T, curr: T) => boolean): T;
     /**
-     * Returns the Room of the nearest RoomProvider above in the React component
-     * tree.
-     */
-    useRoom(): Room<TPresence, TStorage, TUserMeta, TRoomEvent>;
-    /**
-     * Gets the current user once it is connected to the room.
+     * Returns an array of connection IDs. This matches the values you'll get by
+     * using the `useOthers()` hook.
+     *
+     * Roughly equivalent to:
+     *   useOthers((others) => others.map(other => other.connectionId), shallow)
+     *
+     * This is useful in particular to implement efficiently rendering components
+     * for each user in the room, e.g. cursors.
      *
      * @example
-     * const me = useSelf();
-     * const { x, y } = me.presence.cursor;
+     * const ids = useConnectionIds();
+     * // [2, 4, 7]
      */
-    useSelf(): User<TPresence, TUserMeta> | null;
+    useConnectionIds(): readonly number[];
     /**
-     * Extract arbitrary data based on the current user.
+     * Related to useOthers(), but optimized for selecting only "subsets" of
+     * others. This is useful for performance reasons in particular, because
+     * selecting only a subset of users also means limiting the number of
+     * re-renders that will be triggered.
      *
-     * The selector function will get re-evaluated any time your presence data
-     * changes.
-     *
-     * The component that uses this hook will automatically re-render if your
-     * selector function returns a different value from its previous run.
+     * @example
+     * const avatars = useOthersWithData(user => user.info.avatar);
+     * //    ^^^^^^^
+     * //    { connectionId: number; data: string }[]
      *
-     * By default `useSelf()` uses strict `===` to check for equality. Take extra
-     * care when returning a computed object or list, for example when you 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.
+     * The selector function you pass to useOthersWithData() 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.
      *
-     * Will return `null` while Liveblocks isn't connected to a room yet.
+     * For example, to select multiple properties:
      *
      * @example
-     * const cursor = useSelf(me => me.presence.cursor);
-     * if (cursor !== null) {
-     *   const { x, y } = cursor;
-     * }
+     * const avatarsAndCursors = useOthersWithData(
+     *   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;
+    }[];
+    /**
+     * 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.
      *
+     * @example
+     * // Returns full user and re-renders whenever anything on the user changes
+     * const secondUser = useOther(2);
      */
-    useSelf<T>(selector: (me: User<TPresence, TUserMeta>) => T, isEqual?: (a: T, b: T) => boolean): T | null;
+    useOther(connectionId: number): User<TPresence, TUserMeta>;
     /**
-     * Returns the mutable (!) Storage root. This hook exists for
-     * backward-compatible reasons.
+     * 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.
      *
      * @example
-     * const [root] = useStorageRoot();
+     * // Returns only the selected values re-renders whenever that selection changes)
+     * const { x, y } = useOther(2, user => user.presence.cursor);
      */
-    useStorageRoot(): [root: LiveObject<TStorage> | null];
+    useOther<T>(connectionId: number, selector: (other: User<TPresence, TUserMeta>) => T, isEqual?: (prev: T, curr: T) => boolean): T;
     /**
      * useUpdateMyPresence is similar to useMyPresence but it only returns the function to update the current user presence.
      * If you don't use the current user presence in your component, but you need to update it (e.g. live cursor), it's better to use useUpdateMyPresence to avoid unnecessary renders.
@@ -269,16 +362,418 @@ declare type RoomContextBundle<TPresence extends JsonObject, TStorage extends Ls
     useUpdateMyPresence(): (patch: Partial<TPresence>, options?: {
         addToHistory: boolean;
     }) => void;
-    useMutation<F extends (context: MutationContext<TPresence, TStorage>, ...args: any[]) => any>(callback: F, deps?: unknown[]): OmitFirstArg<F>;
+    /**
+     * Create a callback function that can be called to mutate Liveblocks state.
+     *
+     * The first argument that gets passed into your callback will be a "mutation
+     * context", which exposes the following:
+     *
+     *   - `root` - The mutable Storage root.
+     *              You can normal mutation on Live structures with this, for
+     *              example: root.get('layers').get('layer1').set('fill', 'red')
+     *
+     *   - `setMyPresence` - Call this with a new (partial) Presence value.
+     *
+     *   - `self` - A read-only version of the latest self, if you need it to
+     *              compute the next state.
+     *
+     *   - `others` - A read-only version of the latest others list, if you need
+     *                it to compute the next state.
+     *
+     * useMutation is like React's useCallback, except that the first argument
+     * that gets passed into your callback will be a "mutation context".
+     *
+     * If you want get access to the immutable root somewhere in your mutation,
+     * you can use `root.ToImmutable()`.
+     *
+     * @example
+     * const fillLayers = useMutation(
+     *   ({ root }, color: Color) => {
+     *     ...
+     *   },
+     *   [],
+     * );
+     *
+     * fillLayers('red');
+     *
+     * const deleteLayers = useMutation(
+     *   ({ root }) => {
+     *     ...
+     *   },
+     *   [],
+     * );
+     *
+     * deleteLayers();
+     */
+    useMutation<F extends (context: MutationContext<TPresence, TStorage, TUserMeta>, ...args: any[]) => any>(callback: F, deps: readonly unknown[]): OmitFirstArg<F>;
     suspense: {
+        /**
+         * You normally don't need to directly interact with the RoomContext, but
+         * it can be necessary if you're building an advanced app where you need to
+         * set up a context bridge between two React renderers.
+         */
+        RoomContext: React.Context<Room<TPresence, TStorage, TUserMeta, TRoomEvent> | null>;
+        /**
+         * Makes a Room available in the component hierarchy below.
+         * When this component is unmounted, the current user leave the room.
+         * That means that you can't have 2 RoomProvider with the same room id in your react tree.
+         */
+        RoomProvider(props: RoomProviderProps<TPresence, TStorage>): JSX.Element;
+        /**
+         * Returns the Room of the nearest RoomProvider above in the React component
+         * tree.
+         */
+        useRoom(): Room<TPresence, TStorage, TUserMeta, TRoomEvent>;
+        /**
+         * Returns a function that batches modifications made during the given function.
+         * All the modifications are sent to other clients in a single message.
+         * All the modifications are merged in a single history item (undo/redo).
+         * All the subscribers are called only after the batch is over.
+         */
+        useBatch<T>(): (callback: () => T) => T;
+        /**
+         * Returns a callback that lets you broadcast custom events to other users in the room
+         *
+         * @example
+         * const broadcast = useBroadcastEvent();
+         *
+         * broadcast({ type: "CUSTOM_EVENT", data: { x: 0, y: 0 } });
+         */
+        useBroadcastEvent(): (event: TRoomEvent, options?: BroadcastOptions) => void;
+        /**
+         * useErrorListener is a react hook that lets you react to potential room connection errors.
+         *
+         * @example
+         * useErrorListener(er => {
+         *   console.error(er);
+         * })
+         */
+        useErrorListener(callback: (err: Error) => void): void;
+        /**
+         * useEventListener is a react hook that lets you react to event broadcasted by other users in the room.
+         *
+         * @example
+         * useEventListener(({ connectionId, event }) => {
+         *   if (event.type === "CUSTOM_EVENT") {
+         *     // Do something
+         *   }
+         * });
+         */
+        useEventListener(callback: (eventData: {
+            connectionId: number;
+            event: TRoomEvent;
+        }) => void): void;
+        /**
+         * Returns the room.history
+         */
+        useHistory(): History;
+        /**
+         * Returns a function that undoes the last operation executed by the current client.
+         * It does not impact operations made by other clients.
+         */
+        useUndo(): () => void;
+        /**
+         * Returns a function that redoes the last operation executed by the current client.
+         * It does not impact operations made by other clients.
+         */
+        useRedo(): () => void;
+        /**
+         * Returns whether there are any operations to undo.
+         */
+        useCanUndo(): boolean;
+        /**
+         * Returns whether there are any operations to redo.
+         */
+        useCanRedo(): boolean;
+        /**
+         * Returns the mutable (!) Storage root. This hook exists for
+         * backward-compatible reasons.
+         *
+         * @example
+         * 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>;
-        useStorage<T>(selector: (root: ToImmutable<TStorage>) => T, isEqual?: (a: T, b: T) => boolean): T;
+        /**
+         * Extract arbitrary data from the Liveblocks Storage state, using an
+         * arbitrary selector function.
+         *
+         * The selector function will get re-evaluated any time something changes in
+         * Storage. The value returned by your selector function will also be the
+         * value returned by the hook.
+         *
+         * The `root` value that gets passed to your selector function is
+         * a immutable/readonly version of your Liveblocks storage root.
+         *
+         * The component that uses this hook will automatically re-render if the
+         * returned value changes.
+         *
+         * By default `useStorage()` uses strict `===` to check for equality. Take
+         * extra care when returning a computed object or list, for example when you
+         * 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;
+        /**
+         * Gets the current user once it is connected to the room.
+         *
+         * @example
+         * const me = useSelf();
+         * const { x, y } = me.presence.cursor;
+         */
         useSelf(): User<TPresence, TUserMeta>;
-        useSelf<T>(selector: (me: User<TPresence, TUserMeta>) => T, isEqual?: (a: T, b: T) => boolean): T;
+        /**
+         * Extract arbitrary data based on the current user.
+         *
+         * The selector function will get re-evaluated any time your presence data
+         * changes.
+         *
+         * The component that uses this hook will automatically re-render if your
+         * selector function returns a different value from its previous run.
+         *
+         * By default `useSelf()` uses strict `===` to check for equality. Take extra
+         * care when returning a computed object or list, for example when you 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.
+         *
+         * Will return `null` while Liveblocks isn't connected to a room yet.
+         *
+         * @example
+         * const cursor = useSelf(me => me.presence.cursor);
+         * if (cursor !== null) {
+         *   const { x, y } = cursor;
+         * }
+         *
+         */
+        useSelf<T>(selector: (me: User<TPresence, TUserMeta>) => T, isEqual?: (prev: T, curr: T) => boolean): T;
+        /**
+         * Returns the presence of the current user of the current room, and a function to update it.
+         * It is different from the setState function returned by the useState hook from React.
+         * You don't need to pass the full presence object to update it.
+         *
+         * @example
+         * const [myPresence, updateMyPresence] = useMyPresence();
+         * updateMyPresence({ x: 0 });
+         * updateMyPresence({ y: 0 });
+         *
+         * // At the next render, "myPresence" will be equal to "{ x: 0, y: 0 }"
+         */
+        useMyPresence(): [
+            TPresence,
+            (patch: Partial<TPresence>, options?: {
+                addToHistory: boolean;
+            }) => void
+        ];
+        /**
+         * Returns an object that lets you get information about all the users
+         * currently connected in the room.
+         *
+         * @example
+         * const others = useOthers();
+         *
+         * // Example to map all cursors in JSX
+         * return (
+         *   <>
+         *     {others.map((user) => {
+         *        if (user.presence.cursor == null) {
+         *          return null;
+         *        }
+         *        return <Cursor key={user.connectionId} cursor={user.presence.cursor} />
+         *      })}
+         *   </>
+         * )
+         */
         useOthers(): Others<TPresence, TUserMeta>;
-        useOthers<T>(selector: (others: Others<TPresence, TUserMeta>) => T, isEqual?: (a: T, b: T) => boolean): T;
+        /**
+         * Extract arbitrary data based on all the users currently connected in the
+         * room (except yourself).
+         *
+         * The selector function will get re-evaluated any time a user enters or
+         * leaves the room, as well as whenever their presence data changes.
+         *
+         * The component that uses this hook will automatically re-render if your
+         * selector function returns a different value from its previous run.
+         *
+         * By default `useOthers()` uses strict `===` to check for equality. Take
+         * extra care when returning a computed object or list, for example when you
+         * 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.
+         *
+         * @example
+         * const avatars = useOthers(users => users.map(u => u.info.avatar), shallow);
+         * const cursors = useOthers(users => users.map(u => u.presence.cursor), shallow);
+         * const someoneIsTyping = useOthers(users => users.some(u => u.presence.isTyping));
+         *
+         */
+        useOthers<T>(selector: (others: Others<TPresence, TUserMeta>) => T, isEqual?: (prev: T, curr: T) => boolean): T;
+        /**
+         * Returns an array of connection IDs. This matches the values you'll get by
+         * using the `useOthers()` hook.
+         *
+         * Roughly equivalent to:
+         *   useOthers((others) => others.map(other => other.connectionId), shallow)
+         *
+         * This is useful in particular to implement efficiently rendering components
+         * for each user in the room, e.g. cursors.
+         *
+         * @example
+         * const ids = useConnectionIds();
+         * // [2, 4, 7]
+         */
+        useConnectionIds(): readonly number[];
+        /**
+         * Related to useOthers(), but optimized for selecting only "subsets" of
+         * others. This is useful for performance reasons in particular, because
+         * selecting only a subset of users also means limiting the number of
+         * re-renders that will be triggered.
+         *
+         * @example
+         * const avatars = useOthersWithData(user => user.info.avatar);
+         * //    ^^^^^^^
+         * //    { connectionId: number; data: string }[]
+         *
+         * The selector function you pass to useOthersWithData() 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.
+         *
+         * For example, to select multiple properties:
+         *
+         * @example
+         * const avatarsAndCursors = useOthersWithData(
+         *   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;
+        }[];
+        /**
+         * 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.
+         *
+         * @example
+         * // Returns full user and re-renders whenever anything on the user changes
+         * const secondUser = useOther(2);
+         */
+        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.
+         *
+         * @example
+         * // Returns only the selected values re-renders whenever that selection changes)
+         * const { x, y } = useOther(2, user => user.presence.cursor);
+         */
+        useOther<T>(connectionId: number, selector: (other: User<TPresence, TUserMeta>) => T, isEqual?: (prev: T, curr: T) => boolean): T;
+        /**
+         * useUpdateMyPresence is similar to useMyPresence but it only returns the function to update the current user presence.
+         * If you don't use the current user presence in your component, but you need to update it (e.g. live cursor), it's better to use useUpdateMyPresence to avoid unnecessary renders.
+         *
+         * @example
+         * const updateMyPresence = useUpdateMyPresence();
+         * updateMyPresence({ x: 0 });
+         * updateMyPresence({ y: 0 });
+         *
+         * // At the next render, the presence of the current user will be equal to "{ x: 0, y: 0 }"
+         */
+        useUpdateMyPresence(): (patch: Partial<TPresence>, options?: {
+            addToHistory: boolean;
+        }) => void;
+        /**
+         * Create a callback function that can be called to mutate Liveblocks
+         * state.
+         *
+         * The first argument that gets passed into your callback will be
+         * a "mutation context", which exposes the following:
+         *
+         *   - `root` - The mutable Storage root.
+         *              You can normal mutation on Live structures with this, for
+         *              example: root.get('layers').get('layer1').set('fill',
+         *              'red')
+         *
+         *   - `setMyPresence` - Call this with a new (partial) Presence value.
+         *
+         *   - `self` - A read-only version of the latest self, if you need it to
+         *              compute the next state.
+         *
+         *   - `others` - A read-only version of the latest others list, if you
+         *                need it to compute the next state.
+         *
+         * useMutation is like React's useCallback, except that the first argument
+         * that gets passed into your callback will be a "mutation context".
+         *
+         * If you want get access to the immutable root somewhere in your mutation,
+         * you can use `root.ToImmutable()`.
+         *
+         * @example
+         * const fillLayers = useMutation(
+         *   ({ root }, color: Color) => {
+         *     ...
+         *   },
+         *   [],
+         * );
+         *
+         * fillLayers('red');
+         *
+         * const deleteLayers = useMutation(
+         *   ({ root }) => {
+         *     ...
+         *   },
+         *   [],
+         * );
+         *
+         * deleteLayers();
+         */
+        useMutation<F extends (context: MutationContext<TPresence, TStorage, TUserMeta>, ...args: any[]) => any>(callback: F, deps: readonly unknown[]): OmitFirstArg<F>;
+        /**
+         * Returns the LiveList associated with the provided key. The hook triggers
+         * a re-render if the LiveList is updated, however it does not triggers
+         * a re-render if a nested CRDT is updated.
+         *
+         * @param key The storage key associated with the LiveList
+         * @returns null while the storage is loading, otherwise, returns the LiveList associated to the storage
+         *
+         * @example
+         * const animals = useList("animals");  // e.g. [] or ["🦁", "🐍", "🦍"]
+         */
+        useList<TKey extends Extract<keyof TStorage, string>>(key: TKey): TStorage[TKey];
+        /**
+         * Returns the LiveMap associated with the provided key. If the LiveMap
+         * does not exist, a new empty LiveMap will be created. The hook triggers
+         * a re-render if the LiveMap is updated, however it does not triggers
+         * a re-render if a nested CRDT is updated.
+         *
+         * @param key The storage key associated with the LiveMap
+         * @returns null while the storage is loading, otherwise, returns the LiveMap associated to the storage
+         *
+         * @example
+         * const shapesById = useMap("shapes");
+         */
+        useMap<TKey extends Extract<keyof TStorage, string>>(key: TKey): TStorage[TKey];
+        /**
+         * Returns the LiveObject associated with the provided key.
+         * The hook triggers a re-render if the LiveObject is updated, however it does not triggers a re-render if a nested CRDT is updated.
+         *
+         * @param key The storage key associated with the LiveObject
+         * @returns null while the storage is loading, otherwise, returns the LveObject associated to the storage
+         *
+         * @example
+         * const object = useObject("obj");
+         */
+        useObject<TKey extends Extract<keyof TStorage, string>>(key: TKey): TStorage[TKey];
     };
 };
+
 declare function createRoomContext<TPresence extends JsonObject, TStorage extends LsonObject = LsonObject, TUserMeta extends BaseUserMeta = BaseUserMeta, TRoomEvent extends Json = never>(client: Client): RoomContextBundle<TPresence, TStorage, TUserMeta, TRoomEvent>;
 
-export { MutationContext, createRoomContext };
+export { ClientSideSuspense, MutationContext, createRoomContext };

package/index.js

@@ -1,6 +1,19 @@
-"use strict";Object.defineProperty(exports, "__esModule", {value: true}); function _interopRequireWildcard(obj) { if (obj && obj.__esModule) { return obj; } else { var newObj = {}; if (obj != null) { for (var key in obj) { if (Object.prototype.hasOwnProperty.call(obj, key)) { newObj[key] = obj[key]; } } } newObj.default = obj; return newObj; } }// src/factory.tsx
+"use strict";Object.defineProperty(exports, "__esModule", {value: true}); function _interopRequireWildcard(obj) { if (obj && obj.__esModule) { return obj; } else { var newObj = {}; if (obj != null) { for (var key in obj) { if (Object.prototype.hasOwnProperty.call(obj, key)) { newObj[key] = obj[key]; } } } newObj.default = obj; return newObj; } }// src/ClientSideSuspense.tsx
+var _react = require('react'); var React = _interopRequireWildcard(_react); var React2 = _interopRequireWildcard(_react);
+function ClientSideSuspense(props) {
+  const [mounted, setMounted] = React.useState(false);
+  React.useEffect(() => {
+    setMounted(true);
+  }, []);
+  return /* @__PURE__ */ React.createElement(React.Suspense, {
+    fallback: props.fallback
+  }, mounted ? props.children() : props.fallback);
+}
+
+// src/factory.tsx
+var _client = require('@liveblocks/client');
 var _internal = require('@liveblocks/client/internal');
-var _react = require('react'); var React = _interopRequireWildcard(_react);
+
 var _withselector = require('use-sync-external-store/shim/with-selector');
 
 // src/hooks.ts
@@ -20,25 +33,46 @@ function useInitial(value) {
 var noop = () => {
 };
 var identity = (x) => x;
-var EMPTY_OTHERS = [];
-Object.defineProperty(EMPTY_OTHERS, "count", {
-  value: 0,
-  enumerable: false
-});
-Object.defineProperty(EMPTY_OTHERS, "toArray", {
-  value: () => EMPTY_OTHERS,
-  enumerable: false
-});
-_internal.freeze.call(void 0, EMPTY_OTHERS);
+function useSyncExternalStore(s, g, gg) {
+  return _withselector.useSyncExternalStoreWithSelector.call(void 0, s, g, gg, identity);
+}
+var EMPTY_OTHERS = _internal.asArrayWithLegacyMethods.call(void 0, []);
 function getEmptyOthers() {
   return EMPTY_OTHERS;
 }
+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) {
+        throw new Error(errmsg);
+      }
+      return root;
+    },
+    get self() {
+      const self = room.getSelf();
+      if (self === null) {
+        throw new Error(errmsg);
+      }
+      return self;
+    },
+    get others() {
+      const others = room.getOthers();
+      if (!room.isSelfAware()) {
+        throw new Error(errmsg);
+      }
+      return others;
+    },
+    setMyPresence: room.updatePresence
+  };
+}
 function createRoomContext(client) {
-  const RoomContext = React.createContext(null);
+  const RoomContext = React2.createContext(null);
   function RoomProvider(props) {
     const { id: roomId, initialPresence, initialStorage } = props;
     if (process.env.NODE_ENV !== "production") {
-      if (roomId == null) {
+      if (!roomId) {
         throw new Error(
           "RoomProvider id property is required. For more information: https://liveblocks.io/docs/errors/liveblocks-react/RoomProvider-id-property-is-required"
         );
@@ -51,14 +85,14 @@ function createRoomContext(client) {
       initialPresence,
       initialStorage
     });
-    const [room, setRoom] = React.useState(
+    const [room, setRoom] = React2.useState(
       () => client.enter(roomId, {
         initialPresence,
         initialStorage,
         DO_NOT_USE_withoutConnecting: typeof window === "undefined"
       })
     );
-    React.useEffect(() => {
+    React2.useEffect(() => {
       setRoom(
         client.enter(roomId, {
           initialPresence: frozen.initialPresence,
@@ -70,26 +104,26 @@ function createRoomContext(client) {
         client.leave(roomId);
       };
     }, [roomId, frozen]);
-    return /* @__PURE__ */ React.createElement(RoomContext.Provider, {
+    return /* @__PURE__ */ React2.createElement(RoomContext.Provider, {
       value: room
     }, props.children);
   }
+  function connectionIdSelector(others) {
+    return others.map((user) => user.connectionId);
+  }
   function useRoom() {
-    const room = React.useContext(RoomContext);
-    if (room == null) {
+    const room = React2.useContext(RoomContext);
+    if (room === null) {
       throw new Error("RoomProvider is missing from the react tree");
     }
     return room;
   }
   function useMyPresence() {
     const room = useRoom();
-    const presence = room.getPresence();
-    const rerender = useRerender();
-    React.useEffect(() => room.events.me.subscribe(rerender), [room, rerender]);
-    const setPresence = React.useCallback(
-      (patch, options) => room.updatePresence(patch, options),
-      [room]
-    );
+    const subscribe = room.events.me.subscribe;
+    const getSnapshot = room.getPresence;
+    const presence = useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
+    const setPresence = room.updatePresence;
     return [presence, setPresence];
   }
   function useUpdateMyPresence() {
@@ -98,10 +132,7 @@ function createRoomContext(client) {
   function useOthers(selector, isEqual) {
     const room = useRoom();
     const subscribe = room.events.others.subscribe;
-    const getSnapshot = React.useCallback(
-      () => room.getOthers(),
-      [room]
-    );
+    const getSnapshot = room.getOthers;
     const getServerSnapshot = getEmptyOthers;
     return _withselector.useSyncExternalStoreWithSelector.call(void 0, 
       subscribe,
@@ -111,9 +142,77 @@ function createRoomContext(client) {
       isEqual
     );
   }
+  function useConnectionIds() {
+    return useOthers(connectionIdSelector, _client.shallow);
+  }
+  function useOthersWithData(itemSelector, itemIsEqual) {
+    const wrappedSelector = React2.useCallback(
+      (others) => others.map((other) => ({
+        connectionId: other.connectionId,
+        data: itemSelector(other)
+      })),
+      [itemSelector]
+    );
+    const wrappedIsEqual = React2.useCallback(
+      (a, b) => {
+        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);
+        });
+      },
+      [itemIsEqual]
+    );
+    return useOthers(wrappedSelector, wrappedIsEqual);
+  }
+  const sentinel = Symbol();
+  function useOther(connectionId, selector, isEqual) {
+    const _useCallback = React2.useCallback;
+    const _useOthers = useOthers;
+    if (selector === void 0) {
+      const selector2 = _useCallback(
+        (others) => others.find((other2) => other2.connectionId === connectionId),
+        [connectionId]
+      );
+      const other = _useOthers(selector2, _client.shallow);
+      if (other === void 0) {
+        throw new Error(
+          `No such other user with connection id ${connectionId} exists`
+        );
+      }
+      return other;
+    } else {
+      const wrappedSelector = _useCallback(
+        (others) => {
+          const other2 = others.find(
+            (other3) => other3.connectionId === connectionId
+          );
+          return other2 !== void 0 ? selector(other2) : sentinel;
+        },
+        [connectionId, selector]
+      );
+      const wrappedIsEqual = _useCallback(
+        (prev, curr) => {
+          if (prev === sentinel || curr === sentinel) {
+            return prev === curr;
+          }
+          const eq = isEqual != null ? isEqual : Object.is;
+          return eq(prev, curr);
+        },
+        [isEqual]
+      );
+      const other = _useOthers(wrappedSelector, wrappedIsEqual);
+      if (other === sentinel) {
+        throw new Error(
+          `No such other user with connection id ${connectionId} exists`
+        );
+      }
+      return other;
+    }
+  }
   function useBroadcastEvent() {
     const room = useRoom();
-    return React.useCallback(
+    return React2.useCallback(
       (event, options = { shouldQueueEventIfNotReady: false }) => {
         room.broadcastEvent(event, options);
       },
@@ -122,22 +221,22 @@ function createRoomContext(client) {
   }
   function useErrorListener(callback) {
     const room = useRoom();
-    const savedCallback = React.useRef(callback);
-    React.useEffect(() => {
+    const savedCallback = React2.useRef(callback);
+    React2.useEffect(() => {
       savedCallback.current = callback;
     });
-    React.useEffect(
+    React2.useEffect(
       () => room.events.error.subscribe((e) => savedCallback.current(e)),
       [room]
     );
   }
   function useEventListener(callback) {
     const room = useRoom();
-    const savedCallback = React.useRef(callback);
-    React.useEffect(() => {
+    const savedCallback = React2.useRef(callback);
+    React2.useEffect(() => {
       savedCallback.current = callback;
     });
-    React.useEffect(() => {
+    React2.useEffect(() => {
       const listener = (eventData) => {
         savedCallback.current(eventData);
       };
@@ -146,7 +245,7 @@ function createRoomContext(client) {
   }
   function useSelf(maybeSelector, isEqual) {
     const room = useRoom();
-    const subscribe = React.useCallback(
+    const subscribe = React2.useCallback(
       (onChange) => {
         const unsub1 = room.events.me.subscribe(onChange);
         const unsub2 = room.events.connection.subscribe(onChange);
@@ -159,11 +258,11 @@ function createRoomContext(client) {
     );
     const getSnapshot = room.getSelf;
     const selector = maybeSelector != null ? maybeSelector : identity;
-    const wrappedSelector = React.useCallback(
+    const wrappedSelector = React2.useCallback(
       (me) => me !== null ? selector(me) : null,
       [selector]
     );
-    const getServerSnapshot = React.useCallback(() => null, []);
+    const getServerSnapshot = React2.useCallback(() => null, []);
     return _withselector.useSyncExternalStoreWithSelector.call(void 0, 
       subscribe,
       getSnapshot,
@@ -176,14 +275,8 @@ function createRoomContext(client) {
     const room = useRoom();
     const subscribe = room.events.storageDidLoad.subscribeOnce;
     const getSnapshot = room.getStorageSnapshot;
-    const getServerSnapshot = React.useCallback(() => null, []);
-    const selector = identity;
-    return _withselector.useSyncExternalStoreWithSelector.call(void 0, 
-      subscribe,
-      getSnapshot,
-      getServerSnapshot,
-      selector
-    );
+    const getServerSnapshot = React2.useCallback(() => null, []);
+    return useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot);
   }
   function useStorageRoot() {
     return [useMutableStorageRoot()];
@@ -199,21 +292,15 @@ function createRoomContext(client) {
   }
   function useCanUndo() {
     const room = useRoom();
-    const [canUndo, setCanUndo] = React.useState(room.history.canUndo);
-    React.useEffect(
-      () => room.events.history.subscribe(({ canUndo: canUndo2 }) => setCanUndo(canUndo2)),
-      [room]
-    );
-    return canUndo;
+    const subscribe = room.events.history.subscribe;
+    const canUndo = room.history.canUndo;
+    return useSyncExternalStore(subscribe, canUndo, canUndo);
   }
   function useCanRedo() {
     const room = useRoom();
-    const [canRedo, setCanRedo] = React.useState(room.history.canRedo);
-    React.useEffect(
-      () => room.events.history.subscribe(({ canRedo: canRedo2 }) => setCanRedo(canRedo2)),
-      [room]
-    );
-    return canRedo;
+    const subscribe = room.events.history.subscribe;
+    const canRedo = room.history.canRedo;
+    return useSyncExternalStore(subscribe, canRedo, canRedo);
   }
   function useBatch() {
     return useRoom().batch;
@@ -222,8 +309,8 @@ function createRoomContext(client) {
     const room = useRoom();
     const root = useMutableStorageRoot();
     const rerender = useRerender();
-    React.useEffect(() => {
-      if (root == null) {
+    React2.useEffect(() => {
+      if (root === null) {
         return;
       }
       let liveValue = root.get(key);
@@ -253,7 +340,7 @@ function createRoomContext(client) {
         unsubscribeCrdt();
       };
     }, [root, room, key, rerender]);
-    if (root == null) {
+    if (root === null) {
       return null;
     } else {
       return root.get(key);
@@ -263,15 +350,15 @@ function createRoomContext(client) {
     const room = useRoom();
     const rootOrNull = useMutableStorageRoot();
     const selector = maybeSelector != null ? maybeSelector : identity;
-    const wrappedSelector = React.useCallback(
+    const wrappedSelector = React2.useCallback(
       (rootOrNull2) => rootOrNull2 !== null ? selector(rootOrNull2) : null,
       [selector]
     );
-    const subscribe = React.useCallback(
+    const subscribe = React2.useCallback(
       (onStoreChange) => rootOrNull !== null ? room.subscribe(rootOrNull, onStoreChange, { isDeep: true }) : noop,
       [room, rootOrNull]
     );
-    const getSnapshot = React.useCallback(() => {
+    const getSnapshot = React2.useCallback(() => {
       if (rootOrNull === null) {
         return null;
       } else {
@@ -280,7 +367,7 @@ function createRoomContext(client) {
         return imm;
       }
     }, [rootOrNull]);
-    const getServerSnapshot = React.useCallback(() => null, []);
+    const getServerSnapshot = React2.useCallback(() => null, []);
     return _withselector.useSyncExternalStoreWithSelector.call(void 0, 
       subscribe,
       getSnapshot,
@@ -318,31 +405,13 @@ function createRoomContext(client) {
   }
   function useMutation(callback, deps) {
     const room = useRoom();
-    const root = useMutableStorageRoot();
-    const setMyPresence = room.updatePresence;
-    return React.useMemo(
+    return React2.useMemo(
       () => {
-        if (root !== null) {
-          const mutationCtx = {
-            root,
-            setMyPresence
-          };
-          return (...args) => {
-            let rv;
-            room.batch(() => {
-              rv = callback(mutationCtx, ...args);
-            });
-            return rv;
-          };
-        } else {
-          return () => {
-            throw new Error(
-              "Mutation cannot be called while Liveblocks Storage has not loaded yet"
-            );
-          };
-        }
+        return (...args) => room.batch(
+          () => callback(makeMutationContext(room), ...args)
+        );
       },
-      deps !== void 0 ? [root, room, setMyPresence, ...deps] : [root, room, setMyPresence, callback]
+      [room, ...deps]
     );
   }
   function useStorageSuspense(selector, isEqual) {
@@ -366,36 +435,82 @@ function createRoomContext(client) {
       isEqual
     );
   }
+  function useOthersWithDataSuspense(itemSelector, itemIsEqual) {
+    useSuspendUntilPresenceLoaded();
+    return useOthersWithData(itemSelector, itemIsEqual);
+  }
+  function useOtherSuspense(connectionId, selector, isEqual) {
+    useSuspendUntilPresenceLoaded();
+    return useOther(
+      connectionId,
+      selector,
+      isEqual
+    );
+  }
+  function useLegacyKeySuspense(key) {
+    useSuspendUntilStorageLoaded();
+    return useLegacyKey(key);
+  }
   return {
+    RoomContext,
     RoomProvider,
+    useRoom,
     useBatch,
     useBroadcastEvent,
-    useCanRedo,
-    useCanUndo,
     useErrorListener,
     useEventListener,
     useHistory,
-    useMyPresence,
-    useOthers,
+    useUndo,
     useRedo,
-    useRoom,
-    useSelf,
+    useCanRedo,
+    useCanUndo,
+    useList: useLegacyKey,
+    useMap: useLegacyKey,
+    useObject: useLegacyKey,
     useStorageRoot,
     useStorage,
-    useUndo,
+    useSelf,
+    useMyPresence,
     useUpdateMyPresence,
+    useOthers,
+    useOthersWithData,
+    useConnectionIds,
+    useOther,
     useMutation,
-    useList: useLegacyKey,
-    useMap: useLegacyKey,
-    useObject: useLegacyKey,
-    RoomContext,
     suspense: {
+      RoomContext,
+      RoomProvider,
+      useRoom,
+      useBatch,
+      useBroadcastEvent,
+      useErrorListener,
+      useEventListener,
+      useHistory,
+      useUndo,
+      useRedo,
+      useCanRedo,
+      useCanUndo,
+      useList: useLegacyKeySuspense,
+      useMap: useLegacyKeySuspense,
+      useObject: useLegacyKeySuspense,
+      useStorageRoot,
       useStorage: useStorageSuspense,
       useSelf: useSelfSuspense,
-      useOthers: useOthersSuspense
+      useMyPresence,
+      useUpdateMyPresence,
+      useOthers: useOthersSuspense,
+      useOthersWithData: useOthersWithDataSuspense,
+      useConnectionIds,
+      useOther: useOtherSuspense,
+      useMutation
     }
   };
 }
 
+// src/index.ts
+
+
+
+
 
-exports.createRoomContext = createRoomContext;
+exports.ClientSideSuspense = ClientSideSuspense; exports.createRoomContext = createRoomContext; exports.shallow = _client.shallow;

package/index.mjs

@@ -1,4 +1,6 @@
 import mod from "./index.js";
 
 export default mod;
+export const ClientSideSuspense = mod.ClientSideSuspense;
 export const createRoomContext = mod.createRoomContext;
+export const shallow = mod.shallow;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@liveblocks/react",
-  "version": "0.18.0-beta0",
+  "version": "0.18.0-beta3",
   "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-beta0",
+    "@liveblocks/client": "0.18.0-beta3",
     "react": "^16.14.0 || ^17 || ^18"
   },
   "repository": {