@liveblocks/react 0.16.4-beta2 → 0.16.4

package/index.d.ts

@@ -1,6 +1,7 @@
 import * as React from 'react';
 import { Client, Room, Presence, Others, BroadcastOptions, Json, User, LiveObject, Lson, LiveMap, LiveList, LsonObject, History } from '@liveblocks/client';
 export { Json, JsonObject } from '@liveblocks/client';
+import { Resolve, RoomInitializers } from '@liveblocks/client/internal';
 
 declare type LiveblocksProviderProps = {
     children: React.ReactNode;
@@ -16,19 +17,13 @@ declare function LiveblocksProvider(props: LiveblocksProviderProps): JSX.Element
  */
 declare function useClient(): Client;
 
-declare type RoomProviderProps<TStorage> = {
+declare type RoomProviderProps<TStorage> = Resolve<{
     /**
      * The id of the room you want to connect to
      */
     id: string;
-    /**
-     * A callback that let you initialize the default presence when entering the room.
-     * If ommited, the default presence will be an empty object
-     */
-    defaultPresence?: () => Presence;
-    defaultStorageRoot?: TStorage;
     children: React.ReactNode;
-};
+} & RoomInitializers<Presence, TStorage>>;
 /**
  * Makes a Room available in the component hierarchy below.
  * When this component is unmounted, the current user leave the room.
@@ -150,42 +145,49 @@ declare function useStorage<TStorage extends Record<string, any>>(): [
  * 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
- * @param entries Optional entries that are used to create the LiveMap for the first time
  * @returns null while the storage is loading, otherwise, returns the LiveMap associated to the storage
  *
  * @example
- * const emptyMap = useMap("mapA");
- * const mapWithItems = useMap("mapB", [["keyA", "valueA"], ["keyB", "valueB"]]);
+ * const shapesById = useMap<string, Shape>("shapes");
+ */
+declare function useMap<TKey extends string, TValue extends Lson>(key: string): LiveMap<TKey, TValue> | null;
+/**
+ * @deprecated We no longer recommend initializing the
+ * entries from the useMap() hook. For details, see https://bit.ly/3Niy5aP.
  */
-declare function useMap<TKey extends string, TValue extends Lson>(key: string, entries?: readonly (readonly [TKey, TValue])[] | null | undefined): LiveMap<TKey, TValue> | null;
+declare function useMap<TKey extends string, TValue extends Lson>(key: string, entries: readonly (readonly [TKey, TValue])[] | null): LiveMap<TKey, TValue> | null;
 /**
- * Returns the LiveList associated with the provided key. If the LiveList does not exist, a new LiveList will be created.
+ * 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
- * @param items Optional items that are used to create the LiveList for the first time
  * @returns null while the storage is loading, otherwise, returns the LiveList associated to the storage
  *
  * @example
- * const emptyList = useList("listA");
- * const listWithItems = useList("listB", ["a", "b", "c"]);
+ * const animals = useList("animals");  // e.g. [] or ["🦁", "🐍", "🦍"]
  */
-declare function useList<TValue extends Lson>(key: string, items?: TValue[] | undefined): LiveList<TValue> | null;
+declare function useList<TValue extends Lson>(key: string): LiveList<TValue> | null;
 /**
- * Returns the LiveObject associated with the provided key. If the LiveObject does not exist, it will be created with the initialData parameter.
+ * @deprecated We no longer recommend initializing the
+ * items from the useList() hook. For details, see https://bit.ly/3Niy5aP.
+ */
+declare function useList<TValue extends Lson>(key: string, items: TValue[]): LiveList<TValue> | null;
+/**
+ * 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
- * @param initialData Optional data that is used to create the LiveObject for the first time
  * @returns null while the storage is loading, otherwise, returns the LveObject associated to the storage
  *
  * @example
- * const object = useObject("obj", {
- *   company: "Liveblocks",
- *   website: "https://liveblocks.io"
- * });
+ * const object = useObject("obj");
+ */
+declare function useObject<TData extends LsonObject>(key: string): LiveObject<TData> | null;
+/**
+ * @deprecated We no longer recommend initializing the fields from the
+ * useObject() hook. For details, see https://bit.ly/3Niy5aP.
  */
-declare function useObject<TData extends LsonObject>(key: string, initialData?: TData): LiveObject<TData> | null;
+declare function useObject<TData extends LsonObject>(key: string, initialData: TData): LiveObject<TData> | null;
 /**
  * Returns a function that undoes the last operation executed by the current client.
  * It does not impact operations made by other clients.

package/index.js

@@ -4,6 +4,7 @@ Object.defineProperty(exports, '__esModule', { value: true });
 
 var React = require('react');
 var client = require('@liveblocks/client');
+var internal = require('@liveblocks/client/internal');
 
 function _interopNamespace(e) {
   if (e && e.__esModule) return e;
@@ -89,6 +90,8 @@ function useRerender() {
 var RoomContext = React__namespace.createContext(null);
 function RoomProvider(props) {
   var roomId = props.id,
+      initialPresence = props.initialPresence,
+      initialStorage = props.initialStorage,
       defaultPresence = props.defaultPresence,
       defaultStorageRoot = props.defaultStorageRoot;
 
@@ -102,11 +105,15 @@ function RoomProvider(props) {
     }
   }
 
+  internal.deprecateIf(defaultPresence, "RoomProvider's `defaultPresence` prop will be removed in @liveblocks/react 0.18. Please use `initialPresence` instead. For more info, see https://bit.ly/3Niy5aP", "defaultPresence");
+  internal.deprecateIf(defaultStorageRoot, "RoomProvider's `defaultStorageRoot` prop will be removed in @liveblocks/react 0.18. Please use `initialStorage` instead. For more info, see https://bit.ly/3Niy5aP", "defaultStorageRoot");
   var client = useClient();
 
   var _React$useState = React__namespace.useState(function () {
     return client.enter(roomId, {
-      defaultPresence: defaultPresence ? defaultPresence() : undefined,
+      initialPresence: initialPresence,
+      initialStorage: initialStorage,
+      defaultPresence: defaultPresence,
       defaultStorageRoot: defaultStorageRoot,
       DO_NOT_USE_withoutConnecting: typeof window === "undefined"
     });
@@ -116,7 +123,9 @@ function RoomProvider(props) {
 
   React__namespace.useEffect(function () {
     setRoom(client.enter(roomId, {
-      defaultPresence: defaultPresence ? defaultPresence() : undefined,
+      initialPresence: initialPresence,
+      initialStorage: initialStorage,
+      defaultPresence: defaultPresence,
       defaultStorageRoot: defaultStorageRoot,
       DO_NOT_USE_withoutConnecting: typeof window === "undefined"
     }));
@@ -277,13 +286,37 @@ function useStorage() {
   return [root];
 }
 function useMap(key, entries) {
-  return useCrdt(key, new client.LiveMap(entries));
+  internal.deprecateIf(entries, "Support for initializing entries in useMap() directly will be removed in @liveblocks/react 0.18.\n\nInstead, please initialize this data where you set up your RoomProvider:\n\n    const initialStorage = () => {\n      " + JSON.stringify(key) + ": new LiveMap(...),\n      ...\n    };\n\n    <RoomProvider initialStorage={initialStorage}>\n      ...\n    </RoomProvider>\n\nPlease see https://bit.ly/3Niy5aP for details.");
+  var value = useCrdt(key, new client.LiveMap(entries));
+
+  if (value.status === "ok") {
+    return value.value;
+  } else {
+    internal.deprecateIf(value.status === "notfound", "Key " + JSON.stringify(key) + " was not found in Storage. Starting with 0.18, useMap() will no longer automatically create this key.\n\nInstead, please initialize your storage where you set up your RoomProvider:\n\n    import { LiveMap } from \"@liveblocks/client\";\n\n    const initialStorage = () => {\n      " + JSON.stringify(key) + ": new LiveMap(...),\n      ...\n    };\n\n    <RoomProvider initialStorage={initialStorage}>\n      ...\n    </RoomProvider>\n\nPlease see https://bit.ly/3Niy5aP for details.");
+    return null;
+  }
 }
 function useList(key, items) {
-  return useCrdt(key, new client.LiveList(items));
+  internal.deprecateIf(items, "Support for initializing items in useList() directly will be removed in @liveblocks/react 0.18.\n\nInstead, please initialize this data where you set up your RoomProvider:\n\n    import { LiveList } from \"@liveblocks/client\";\n\n    const initialStorage = () => {\n      " + JSON.stringify(key) + ": new LiveList(...),\n      ...\n    };\n\n    <RoomProvider initialStorage={initialStorage}>\n      ...\n    </RoomProvider>\n\nPlease see https://bit.ly/3Niy5aP for details.");
+  var value = useCrdt(key, new client.LiveList(items));
+
+  if (value.status === "ok") {
+    return value.value;
+  } else {
+    internal.deprecateIf(value.status === "notfound", "Key " + JSON.stringify(key) + " was not found in Storage. Starting with 0.18, useList() will no longer automatically create this key.\n\nInstead, please initialize your storage where you set up your RoomProvider:\n\n    import { LiveList } from \"@liveblocks/client\";\n\n    const initialStorage = () => {\n      " + JSON.stringify(key) + ": new LiveList(...),\n      ...\n    };\n\n    <RoomProvider initialStorage={initialStorage}>\n      ...\n    </RoomProvider>\n\nPlease see https://bit.ly/3Niy5aP for details.");
+    return null;
+  }
 }
 function useObject(key, initialData) {
-  return useCrdt(key, new client.LiveObject(initialData));
+  internal.deprecateIf(initialData, "Support for initializing data in useObject() directly will be removed in @liveblocks/react 0.18.\n\nInstead, please initialize this data where you set up your RoomProvider:\n\n    import { LiveObject } from \"@liveblocks/client\";\n\n    const initialStorage = () => {\n      " + JSON.stringify(key) + ": new LiveObject(...),\n      ...\n    };\n\n    <RoomProvider initialStorage={initialStorage}>\n      ...\n    </RoomProvider>\n\nPlease see https://bit.ly/3Niy5aP for details.");
+  var value = useCrdt(key, new client.LiveObject(initialData));
+
+  if (value.status === "ok") {
+    return value.value;
+  } else {
+    internal.deprecateIf(value.status === "notfound", "Key " + JSON.stringify(key) + " was not found in Storage. Starting with 0.18, useObject() will no longer automatically create this key.\n\nInstead, please initialize your storage where you set up your RoomProvider:\n\n    import { LiveObject } from \"@liveblocks/client\";\n\n    const initialStorage = () => {\n      " + JSON.stringify(key) + ": new LiveObject(...),\n      ...\n    };\n\n    <RoomProvider initialStorage={initialStorage}>\n      ...\n    </RoomProvider>\n\nPlease see https://bit.ly/3Niy5aP for details.");
+    return null;
+  }
 }
 function useUndo() {
   return useRoom().history.undo;
@@ -299,8 +332,6 @@ function useHistory() {
 }
 
 function useCrdt(key, initialCrdt) {
-  var _root$get;
-
   var room = useRoom();
 
   var _useStorage = useStorage(),
@@ -338,7 +369,25 @@ function useCrdt(key, initialCrdt) {
       unsubscribeCrdt();
     };
   }, [root, room]);
-  return (_root$get = root == null ? void 0 : root.get(key)) != null ? _root$get : null;
+
+  if (root == null) {
+    return {
+      status: "loading"
+    };
+  } else {
+    var value = root.get(key);
+
+    if (value == null) {
+      return {
+        status: "notfound"
+      };
+    } else {
+      return {
+        status: "ok",
+        value: value
+      };
+    }
+  }
 }
 
 exports.LiveblocksProvider = LiveblocksProvider;

package/index.mjs

@@ -1,6 +1,7 @@
 import * as React from 'react';
 import { useReducer } from 'react';
 import { LiveMap, LiveList, LiveObject } from '@liveblocks/client';
+import { deprecateIf } from '@liveblocks/client/internal';
 
 const ClientContext = React.createContext(null);
 /**
@@ -76,7 +77,8 @@ const RoomContext = React.createContext(null);
  * That means that you can't have 2 RoomProvider with the same room id in your react tree.
  */
 function RoomProvider(props) {
-    const { id: roomId, defaultPresence, defaultStorageRoot } = props;
+    const { id: roomId, initialPresence, initialStorage, defaultPresence, // Will get removed in 0.18
+    defaultStorageRoot, } = props;
     if (process.env.NODE_ENV !== "production") {
         if (roomId == null) {
             throw new Error("RoomProvider id property is required. For more information: https://liveblocks.io/docs/errors/liveblocks-react/RoomProvider-id-property-is-required");
@@ -85,15 +87,21 @@ function RoomProvider(props) {
             throw new Error("RoomProvider id property should be a string.");
         }
     }
+    deprecateIf(defaultPresence, "RoomProvider's `defaultPresence` prop will be removed in @liveblocks/react 0.18. Please use `initialPresence` instead. For more info, see https://bit.ly/3Niy5aP", "defaultPresence");
+    deprecateIf(defaultStorageRoot, "RoomProvider's `defaultStorageRoot` prop will be removed in @liveblocks/react 0.18. Please use `initialStorage` instead. For more info, see https://bit.ly/3Niy5aP", "defaultStorageRoot");
     const client = useClient();
     const [room, setRoom] = React.useState(() => client.enter(roomId, {
-        defaultPresence: defaultPresence ? defaultPresence() : undefined,
+        initialPresence,
+        initialStorage,
+        defaultPresence,
         defaultStorageRoot,
         DO_NOT_USE_withoutConnecting: typeof window === "undefined",
     }));
     React.useEffect(() => {
         setRoom(client.enter(roomId, {
-            defaultPresence: defaultPresence ? defaultPresence() : undefined,
+            initialPresence,
+            initialStorage,
+            defaultPresence,
             defaultStorageRoot,
             DO_NOT_USE_withoutConnecting: typeof window === "undefined",
         }));
@@ -296,52 +304,132 @@ function useStorage() {
     }, [room]);
     return [root];
 }
-/**
- * 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
- * @param entries Optional entries that are used to create the LiveMap for the first time
- * @returns null while the storage is loading, otherwise, returns the LiveMap associated to the storage
- *
- * @example
- * const emptyMap = useMap("mapA");
- * const mapWithItems = useMap("mapB", [["keyA", "valueA"], ["keyB", "valueB"]]);
- */
 function useMap(key, entries) {
-    return useCrdt(key, new LiveMap(entries));
+    deprecateIf(entries, `Support for initializing entries in useMap() directly will be removed in @liveblocks/react 0.18.
+
+Instead, please initialize this data where you set up your RoomProvider:
+
+    const initialStorage = () => {
+      ${JSON.stringify(key)}: new LiveMap(...),
+      ...
+    };
+
+    <RoomProvider initialStorage={initialStorage}>
+      ...
+    </RoomProvider>
+
+Please see https://bit.ly/3Niy5aP for details.`);
+    const value = useCrdt(key, new LiveMap(entries));
+    //                         ^^^^^^^^^^^^^^^^^^^^
+    //                         NOTE: This param is scheduled for removal in 0.18
+    if (value.status === "ok") {
+        return value.value;
+    }
+    else {
+        deprecateIf(value.status === "notfound", `Key ${JSON.stringify(key)} was not found in Storage. Starting with 0.18, useMap() will no longer automatically create this key.
+
+Instead, please initialize your storage where you set up your RoomProvider:
+
+    import { LiveMap } from "@liveblocks/client";
+
+    const initialStorage = () => {
+      ${JSON.stringify(key)}: new LiveMap(...),
+      ...
+    };
+
+    <RoomProvider initialStorage={initialStorage}>
+      ...
+    </RoomProvider>
+
+Please see https://bit.ly/3Niy5aP for details.`);
+        return null;
+    }
 }
-/**
- * Returns the LiveList associated with the provided key. If the LiveList does not exist, a new LiveList will be created.
- * 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
- * @param items Optional items that are used to create the LiveList for the first time
- * @returns null while the storage is loading, otherwise, returns the LiveList associated to the storage
- *
- * @example
- * const emptyList = useList("listA");
- * const listWithItems = useList("listB", ["a", "b", "c"]);
- */
 function useList(key, items) {
-    return useCrdt(key, new LiveList(items));
+    deprecateIf(items, `Support for initializing items in useList() directly will be removed in @liveblocks/react 0.18.
+
+Instead, please initialize this data where you set up your RoomProvider:
+
+    import { LiveList } from "@liveblocks/client";
+
+    const initialStorage = () => {
+      ${JSON.stringify(key)}: new LiveList(...),
+      ...
+    };
+
+    <RoomProvider initialStorage={initialStorage}>
+      ...
+    </RoomProvider>
+
+Please see https://bit.ly/3Niy5aP for details.`);
+    const value = useCrdt(key, new LiveList(items));
+    //                                           ^^^^^^^^^^^^^^^^^^^
+    //                                           NOTE: This param is scheduled for removal in 0.18
+    if (value.status === "ok") {
+        return value.value;
+    }
+    else {
+        deprecateIf(value.status === "notfound", `Key ${JSON.stringify(key)} was not found in Storage. Starting with 0.18, useList() will no longer automatically create this key.
+
+Instead, please initialize your storage where you set up your RoomProvider:
+
+    import { LiveList } from "@liveblocks/client";
+
+    const initialStorage = () => {
+      ${JSON.stringify(key)}: new LiveList(...),
+      ...
+    };
+
+    <RoomProvider initialStorage={initialStorage}>
+      ...
+    </RoomProvider>
+
+Please see https://bit.ly/3Niy5aP for details.`);
+        return null;
+    }
 }
-/**
- * Returns the LiveObject associated with the provided key. If the LiveObject does not exist, it will be created with the initialData parameter.
- * 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
- * @param initialData Optional data that is used to create the LiveObject for the first time
- * @returns null while the storage is loading, otherwise, returns the LveObject associated to the storage
- *
- * @example
- * const object = useObject("obj", {
- *   company: "Liveblocks",
- *   website: "https://liveblocks.io"
- * });
- */
 function useObject(key, initialData) {
-    return useCrdt(key, new LiveObject(initialData));
+    deprecateIf(initialData, `Support for initializing data in useObject() directly will be removed in @liveblocks/react 0.18.
+
+Instead, please initialize this data where you set up your RoomProvider:
+
+    import { LiveObject } from "@liveblocks/client";
+
+    const initialStorage = () => {
+      ${JSON.stringify(key)}: new LiveObject(...),
+      ...
+    };
+
+    <RoomProvider initialStorage={initialStorage}>
+      ...
+    </RoomProvider>
+
+Please see https://bit.ly/3Niy5aP for details.`);
+    const value = useCrdt(key, new LiveObject(initialData));
+    //                         ^^^^^^^^^^^^^^^^^^^^^^^^^^^
+    //                         NOTE: This param is scheduled for removal in 0.18
+    if (value.status === "ok") {
+        return value.value;
+    }
+    else {
+        deprecateIf(value.status === "notfound", `Key ${JSON.stringify(key)} was not found in Storage. Starting with 0.18, useObject() will no longer automatically create this key.
+
+Instead, please initialize your storage where you set up your RoomProvider:
+
+    import { LiveObject } from "@liveblocks/client";
+
+    const initialStorage = () => {
+      ${JSON.stringify(key)}: new LiveObject(...),
+      ...
+    };
+
+    <RoomProvider initialStorage={initialStorage}>
+      ...
+    </RoomProvider>
+
+Please see https://bit.ly/3Niy5aP for details.`);
+        return null;
+    }
 }
 /**
  * Returns a function that undoes the last operation executed by the current client.
@@ -373,7 +461,6 @@ function useHistory() {
     return useRoom().history;
 }
 function useCrdt(key, initialCrdt) {
-    var _a;
     const room = useRoom();
     const [root] = useStorage();
     const rerender = useRerender();
@@ -403,7 +490,18 @@ function useCrdt(key, initialCrdt) {
             unsubscribeCrdt();
         };
     }, [root, room]);
-    return (_a = root === null || root === void 0 ? void 0 : root.get(key)) !== null && _a !== void 0 ? _a : null;
+    if (root == null) {
+        return { status: "loading" };
+    }
+    else {
+        const value = root.get(key);
+        if (value == null) {
+            return { status: "notfound" };
+        }
+        else {
+            return { status: "ok", value };
+        }
+    }
 }
 
 export { LiveblocksProvider, RoomProvider, useBatch, useBroadcastEvent, useClient, useErrorListener, useEventListener, useHistory, useList, useMap, useMyPresence, useObject, useOthers, useRedo, useRoom, useSelf, useStorage, useUndo, useUpdateMyPresence };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@liveblocks/react",
-  "version": "0.16.4-beta2",
+  "version": "0.16.4",
   "description": "A set of React hooks and providers to use Liveblocks declaratively.",
   "main": "./index.js",
   "module": "./index.mjs",
@@ -27,7 +27,7 @@
   },
   "license": "Apache-2.0",
   "peerDependencies": {
-    "@liveblocks/client": "0.16.4-beta2",
+    "@liveblocks/client": "0.16.4",
     "react": "^16.14.0 || ^17 || ^18"
   },
   "devDependencies": {