@liveblocks/react 0.18.0-beta2 → 0.18.0-beta3

package/.built-by-link-script

@@ -1 +1 @@
-b78a4b6045d3aab4fd9a5e4686ccac3b534923fe
+ee7b9e79d3549611f64024b4247e9a862cfddd34

package/index.d.ts

@@ -1,6 +1,5 @@
-import * as React from 'react';
 import { ReactElement, ReactNode } from 'react';
-import { JsonObject, LsonObject, LiveObject, BaseUserMeta, Json, Client, Room, BroadcastOptions, History, Others, User } from '@liveblocks/client';
+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';
 
@@ -27,25 +26,32 @@ declare type Props = {
  */
 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.
@@ -53,6 +59,11 @@ 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.
@@ -147,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.
      *
@@ -174,6 +193,38 @@ declare type RoomContextBundle<TPresence extends JsonObject, TStorage extends Ls
      * 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;
+    /**
+     * 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.
@@ -235,53 +286,52 @@ declare type RoomContextBundle<TPresence extends JsonObject, TStorage extends Ls
      */
     useOthers<T>(selector: (others: Others<TPresence, TUserMeta>) => T, isEqual?: (prev: T, curr: T) => boolean): T;
     /**
-     * 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.
+     * 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)
      *
-     * Note that there are two ways to use this hook, and depending on how you
-     * call it, the return value will be slightly different.
+     * This is useful in particular to implement efficiently rendering components
+     * for each user in the room, e.g. cursors.
      *
      * @example
-     * const ids = useOtherIds();
-     * //    ^^^ number[]
+     * const ids = useConnectionIds();
+     * // [2, 4, 7]
      */
-    useOtherIds(): readonly number[];
+    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.
      *
-     * Note that there are two ways to use this hook, and depending on how you
-     * call it, the return value will be slightly different.
-     *
      * @example
-     * const avatars = useOtherIds(user => user.info.avatar);
+     * const avatars = useOthersWithData(user => user.info.avatar);
      * //    ^^^^^^^
      * //    { connectionId: number; data: string }[]
      *
-     * The selector function you pass to useOtherIds() is called an "item
+     * 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) comparison function, it will also work on the _item_ level.
+     * (optional) "item comparison" function, it will be used to compare each
+     * item pairwise.
      *
      * For example, to select multiple properties:
      *
      * @example
-     * const avatarsAndCursors = useOtherIds(
+     * const avatarsAndCursors = useOthersWithData(
      *   user => [u.info.avatar, u.presence.cursor],
-     *   shallow,  // ❗️
+     *   shallow,  // 👈
      * );
      */
-    useOtherIds<T>(itemSelector: (other: User<TPresence, TUserMeta>) => T, isEqual?: (prev: T, curr: T) => boolean): readonly {
+    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 `useOtherIds()`), you can call
-     * this selector deep down in your component stack to only have the component
-     * re-render if properties for this particular connection change.
+     * 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
@@ -289,9 +339,9 @@ declare type RoomContextBundle<TPresence extends JsonObject, TStorage extends Ls
      */
     useOther(connectionId: number): User<TPresence, TUserMeta>;
     /**
-     * Given a connection ID (as obtained by using `useOtherIds()`), you can call
-     * this selector deep down in your component stack to only have the component
-     * re-render if properties for this particular connection change.
+     * 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)
@@ -299,84 +349,431 @@ declare type RoomContextBundle<TPresence extends JsonObject, TStorage extends Ls
      */
     useOther<T>(connectionId: number, selector: (other: User<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.
+     * 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 me = useSelf();
-     * const { x, y } = me.presence.cursor;
+     * 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 }"
      */
-    useSelf(): User<TPresence, TUserMeta> | null;
+    useUpdateMyPresence(): (patch: Partial<TPresence>, options?: {
+        addToHistory: boolean;
+    }) => void;
     /**
-     * Extract arbitrary data based on the current user.
+     * Create a callback function that can be called to mutate Liveblocks state.
      *
-     * The selector function will get re-evaluated any time your presence data
-     * changes.
+     * The first argument that gets passed into your callback will be a "mutation
+     * context", which exposes the following:
      *
-     * The component that uses this hook will automatically re-render if your
-     * selector function returns a different value from its previous run.
+     *   - `root` - The mutable Storage root.
+     *              You can normal mutation on Live structures with this, for
+     *              example: root.get('layers').get('layer1').set('fill', 'red')
      *
-     * 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.
+     *   - `setMyPresence` - Call this with a new (partial) Presence value.
      *
-     * Will return `null` while Liveblocks isn't connected to a room yet.
+     *   - `self` - A read-only version of the latest self, if you need it to
+     *              compute the next state.
      *
-     * @example
-     * const cursor = useSelf(me => me.presence.cursor);
-     * if (cursor !== null) {
-     *   const { x, y } = cursor;
-     * }
+     *   - `others` - A read-only version of the latest others list, if you need
+     *                it to compute the next state.
      *
-     */
-    useSelf<T>(selector: (me: User<TPresence, TUserMeta>) => T, isEqual?: (prev: T, curr: T) => boolean): T | null;
-    /**
-     * Returns the mutable (!) Storage root. This hook exists for
-     * backward-compatible reasons.
+     * useMutation is like React's useCallback, except that the first argument
+     * that gets passed into your callback will be a "mutation context".
      *
-     * @example
-     * const [root] = useStorageRoot();
-     */
-    useStorageRoot(): [root: LiveObject<TStorage> | null];
-    /**
-     * 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.
+     * If you want get access to the immutable root somewhere in your mutation,
+     * you can use `root.ToImmutable()`.
      *
      * @example
-     * const updateMyPresence = useUpdateMyPresence();
-     * updateMyPresence({ x: 0 });
-     * updateMyPresence({ y: 0 });
+     * const fillLayers = useMutation(
+     *   ({ root }, color: Color) => {
+     *     ...
+     *   },
+     *   [],
+     * );
      *
-     * // At the next render, the presence of the current user will be equal to "{ x: 0, y: 0 }"
+     * fillLayers('red');
+     *
+     * const deleteLayers = useMutation(
+     *   ({ root }) => {
+     *     ...
+     *   },
+     *   [],
+     * );
+     *
+     * deleteLayers();
      */
-    useUpdateMyPresence(): (patch: Partial<TPresence>, options?: {
-        addToHistory: boolean;
-    }) => void;
-    useMutation<F extends (context: MutationContext<TPresence, TStorage>, ...args: any[]) => any>(callback: F, deps?: unknown[]): OmitFirstArg<F>;
+    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>;
+        /**
+         * 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>;
+        /**
+         * 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>;
+        /**
+         * 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;
-        useOtherIds(): readonly number[];
-        useOtherIds<T>(itemSelector: (other: User<TPresence, TUserMeta>) => T, isEqual?: (prev: T, curr: T) => boolean): readonly {
+        /**
+         * 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 { ClientSideSuspense, MutationContext, createRoomContext };

package/index.js

@@ -33,16 +33,46 @@ function useInitial(value) {
 var noop = () => {
 };
 var identity = (x) => x;
+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 = 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"
         );
@@ -83,17 +113,17 @@ function createRoomContext(client) {
   }
   function useRoom() {
     const room = React2.useContext(RoomContext);
-    if (room == null) {
+    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();
+    const subscribe = room.events.me.subscribe;
+    const getSnapshot = room.getPresence;
+    const presence = useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
     const setPresence = room.updatePresence;
-    React2.useEffect(() => room.events.me.subscribe(rerender), [room, rerender]);
     return [presence, setPresence];
   }
   function useUpdateMyPresence() {
@@ -112,31 +142,28 @@ function createRoomContext(client) {
       isEqual
     );
   }
-  function useOtherIds(itemSelector, isEqual) {
-    const _useCallback = React2.useCallback;
-    const _useOthers = useOthers;
-    if (itemSelector === void 0) {
-      return _useOthers(connectionIdSelector, _client.shallow);
-    } else {
-      const wrappedSelector = _useCallback(
-        (others) => others.map((other) => ({
-          connectionId: other.connectionId,
-          data: itemSelector(other)
-        })),
-        [itemSelector]
-      );
-      const wrappedIsEqual = _useCallback(
-        (a, b) => {
-          const eq = isEqual != null ? isEqual : 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);
-          });
-        },
-        [isEqual]
-      );
-      return _useOthers(wrappedSelector, wrappedIsEqual);
-    }
+  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) {
@@ -249,13 +276,7 @@ function createRoomContext(client) {
     const subscribe = room.events.storageDidLoad.subscribeOnce;
     const getSnapshot = room.getStorageSnapshot;
     const getServerSnapshot = React2.useCallback(() => null, []);
-    const selector = identity;
-    return _withselector.useSyncExternalStoreWithSelector.call(void 0, 
-      subscribe,
-      getSnapshot,
-      getServerSnapshot,
-      selector
-    );
+    return useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot);
   }
   function useStorageRoot() {
     return [useMutableStorageRoot()];
@@ -271,21 +292,15 @@ function createRoomContext(client) {
   }
   function useCanUndo() {
     const room = useRoom();
-    const [canUndo, setCanUndo] = React2.useState(room.history.canUndo);
-    React2.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] = React2.useState(room.history.canRedo);
-    React2.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;
@@ -295,7 +310,7 @@ function createRoomContext(client) {
     const root = useMutableStorageRoot();
     const rerender = useRerender();
     React2.useEffect(() => {
-      if (root == null) {
+      if (root === null) {
         return;
       }
       let liveValue = root.get(key);
@@ -325,7 +340,7 @@ function createRoomContext(client) {
         unsubscribeCrdt();
       };
     }, [root, room, key, rerender]);
-    if (root == null) {
+    if (root === null) {
       return null;
     } else {
       return root.get(key);
@@ -390,27 +405,13 @@ function createRoomContext(client) {
   }
   function useMutation(callback, deps) {
     const room = useRoom();
-    const root = useMutableStorageRoot();
-    const setMyPresence = room.updatePresence;
     return React2.useMemo(
       () => {
-        if (root !== null) {
-          const mutationCtx = {
-            root,
-            setMyPresence
-          };
-          return (...args) => room.batch(
-            () => callback(mutationCtx, ...args)
-          );
-        } 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) {
@@ -434,12 +435,9 @@ function createRoomContext(client) {
       isEqual
     );
   }
-  function useOtherIdsSuspense(itemSelector, isEqual) {
+  function useOthersWithDataSuspense(itemSelector, itemIsEqual) {
     useSuspendUntilPresenceLoaded();
-    return useOtherIds(
-      itemSelector,
-      isEqual
-    );
+    return useOthersWithData(itemSelector, itemIsEqual);
   }
   function useOtherSuspense(connectionId, selector, isEqual) {
     useSuspendUntilPresenceLoaded();
@@ -454,39 +452,57 @@ function createRoomContext(client) {
     return useLegacyKey(key);
   }
   return {
+    RoomContext,
     RoomProvider,
+    useRoom,
     useBatch,
     useBroadcastEvent,
-    useCanRedo,
-    useCanUndo,
     useErrorListener,
     useEventListener,
     useHistory,
-    useMyPresence,
-    useOthers,
-    useOtherIds,
-    useOther,
+    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,
+      useMyPresence,
+      useUpdateMyPresence,
       useOthers: useOthersSuspense,
-      useOtherIds: useOtherIdsSuspense,
+      useOthersWithData: useOthersWithDataSuspense,
+      useConnectionIds,
       useOther: useOtherSuspense,
-      useList: useLegacyKeySuspense,
-      useMap: useLegacyKeySuspense,
-      useObject: useLegacyKeySuspense
+      useMutation
     }
   };
 }

package/package.json

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