@liveblocks/client 0.12.2 → 0.13.1

package/lib/esm/types.d.ts

@@ -1,4 +1,6 @@
-import { LiveObject } from "./doc";
+import type { LiveList } from "./LiveList";
+import type { LiveMap } from "./LiveMap";
+import type { LiveObject } from "./LiveObject";
 export declare type MyPresenceCallback<T extends Presence = Presence> = (me: T) => void;
 export declare type OthersEventCallback<T extends Presence = Presence> = (others: Others<T>, event: OthersEvent<T>) => void;
 export declare type EventCallback = ({ connectionId, event, }: {
@@ -14,17 +16,31 @@ export declare type RoomEventCallbackMap = {
     error: ErrorCallback;
     connection: ConnectionCallback;
 };
+export declare type LiveMapUpdates<TKey extends string = string, TValue = any> = {
+    type: "LiveMap";
+    node: LiveMap<TKey, TValue>;
+};
+export declare type LiveObjectUpdates<TData = any> = {
+    type: "LiveObject";
+    node: LiveObject<TData>;
+};
+export declare type LiveListUpdates<TItem = any> = {
+    type: "LiveList";
+    node: LiveList<TItem>;
+};
+export declare type StorageUpdate = LiveMapUpdates | LiveObjectUpdates | LiveListUpdates;
+export declare type StorageCallback = (updates: StorageUpdate[]) => void;
 export declare type Client = {
     /**
      * Gets a room. Returns null if {@link Client.enter} has not been called previously.
      *
-     * @param roomId - The id of the room
+     * @param roomId The id of the room
      */
     getRoom(roomId: string): Room | null;
     /**
      * Enters a room and returns it.
-     * @param roomId - The id of the room
-     * @param defaultPresence - Optional. Should be serializable to JSON. If omitted, an empty object will be used.
+     * @param roomId The id of the room
+     * @param defaultPresence Optional. Should be serializable to JSON. If omitted, an empty object will be used.
      */
     enter<TStorageRoot extends Record<string, any> = Record<string, any>>(roomId: string, options?: {
         defaultPresence?: Presence;
@@ -32,7 +48,7 @@ export declare type Client = {
     }): Room;
     /**
      * Leaves a room.
-     * @param roomId - The id of the room
+     * @param roomId The id of the room
      */
     leave(roomId: string): void;
 };
@@ -131,85 +147,224 @@ export declare type Room = {
         /**
          * Subscribe to the current user presence updates.
          *
-         * @param listener - the callback that is called every time the current user presence is updated with {@link Room.updatePresence}.
+         * @param listener the callback that is called every time the current user presence is updated with {@link Room.updatePresence}.
          *
          * @example
          * room.subscribe("my-presence", (presence) => {
          *   // Do something
          * });
          */
-        <T extends Presence>(type: "my-presence", listener: MyPresenceCallback<T>): void;
+        <T extends Presence>(type: "my-presence", listener: MyPresenceCallback<T>): () => void;
         /**
          * Subscribe to the other users updates.
          *
-         * @param listener - the callback that is called when a user enters or leaves the room or when a user update its presence.
+         * @param listener the callback that is called when a user enters or leaves the room or when a user update its presence.
          *
          * @example
          * room.subscribe("others", (others) => {
          *   // Do something
          * });
          */
-        <T extends Presence>(type: "others", listener: OthersEventCallback<T>): void;
+        <T extends Presence>(type: "others", listener: OthersEventCallback<T>): () => void;
         /**
          * Subscribe to events broadcasted by {@link Room.broadcastEvent}
          *
-         * @param listener - the callback that is called when a user calls {@link Room.broadcastEvent}
+         * @param listener the callback that is called when a user calls {@link Room.broadcastEvent}
          *
          * @example
          * room.subscribe("event", ({ event, connectionId }) => {
          *   // Do something
          * });
          */
-        (type: "event", listener: EventCallback): void;
+        (type: "event", listener: EventCallback): () => void;
         /**
          * Subscribe to errors thrown in the room.
          */
-        (type: "error", listener: ErrorCallback): void;
+        (type: "error", listener: ErrorCallback): () => void;
         /**
          * Subscribe to connection state updates.
          */
-        (type: "connection", listener: ConnectionCallback): void;
-    };
-    unsubscribe: {
+        (type: "connection", listener: ConnectionCallback): () => void;
         /**
-         * Unsubscribe to the current user presence updates.
+         * Subscribes to changes made on a {@link LiveMap}. Returns an unsubscribe function.
+         * In a future version, we will also expose what exactly changed in the {@link LiveMap}.
          *
-         * @param listener - the callback that has been used with {@link Room.subscribe}("my-presence").
+         * @param listener the callback this called when the {@link LiveMap} changes.
+         *
+         * @returns Unsubscribe function.
          *
          * @example
-         * const onPresenceChange = (presence) => { };
-         * room.subscribe("my-presence", onPresenceChange);
-         * room.unsubscribe("my-presence", onPresenceChange);
+         * const liveMap = new LiveMap();
+         * const unsubscribe = room.subscribe(liveMap, (liveMap) => { });
+         * unsubscribe();
          */
-        <T extends Presence>(type: "my-presence", listener: MyPresenceCallback<T>): void;
+        <TKey extends string, TValue>(liveMap: LiveMap<TKey, TValue>, listener: (liveMap: LiveMap<TKey, TValue>) => void): () => void;
         /**
-         * Unsubscribe to the other users updates.
+         * Subscribes to changes made on a {@link LiveObject}. Returns an unsubscribe function.
+         * In a future version, we will also expose what exactly changed in the {@link LiveObject}.
+         *
+         * @param listener the callback this called when the {@link LiveObject} changes.
          *
-         * @param listener - the callback that has been used with {@link Room.subscribe}("others").
+         * @returns Unsubscribe function.
          *
          * @example
-         * const onOthersChange = (presence) => { };
-         * room.subscribe("others", onOthersChange);
-         * room.unsubscribe("others", onOthersChange);
+         * const liveObject = new LiveObject();
+         * const unsubscribe = room.subscribe(liveObject, (liveObject) => { });
+         * unsubscribe();
          */
-        <T extends Presence>(type: "others", listener: OthersEventCallback<T>): void;
+        <TData>(liveObject: LiveObject<TData>, callback: (liveObject: LiveObject<TData>) => void): () => void;
+        /**
+         * Subscribes to changes made on a {@link LiveList}. Returns an unsubscribe function.
+         * In a future version, we will also expose what exactly changed in the {@link LiveList}.
+         *
+         * @param listener the callback this called when the {@link LiveList} changes.
+         *
+         * @returns Unsubscribe function.
+         *
+         * @example
+         * const liveList = new LiveList();
+         * const unsubscribe = room.subscribe(liveList, (liveList) => { });
+         * unsubscribe();
+         */
+        <TItem>(liveList: LiveList<TItem>, callback: (liveList: LiveList<TItem>) => void): () => void;
+        /**
+         * Subscribes to changes made on a {@link LiveMap} and all the nested data structures. Returns an unsubscribe function.
+         * In a future version, we will also expose what exactly changed in the {@link LiveMap}.
+         *
+         * @param listener the callback this called when the {@link LiveMap} changes.
+         *
+         * @returns Unsubscribe function.
+         *
+         * @example
+         * const liveMap = new LiveMap();
+         * const unsubscribe = room.subscribe(liveMap, (liveMap) => { }, { isDeep: true });
+         * unsubscribe();
+         */
+        <TKey extends string, TValue>(liveMap: LiveMap<TKey, TValue>, callback: (updates: StorageUpdate[]) => void, options: {
+            isDeep: true;
+        }): () => void;
         /**
-         * Unsubscribe to events broadcasted by {@link Room.broadcastEvent}
+         * Subscribes to changes made on a {@link LiveObject} and all the nested data structures. Returns an unsubscribe function.
+         * In a future version, we will also expose what exactly changed in the {@link LiveObject}.
+         *
+         * @param listener the callback this called when the {@link LiveObject} changes.
          *
-         * @param listener - the callback that has been used with {@link Room.unsubscribe}("event").
+         * @returns Unsubscribe function.
          *
          * @example
-         * const onEvent = ({ event, connectionId }) => { };
-         * room.subscribe("event", onEvent);
-         * room.unsubscribe("event", onEvent);
+         * const liveObject = new LiveObject();
+         * const unsubscribe = room.subscribe(liveObject, (liveObject) => { }, { isDeep: true });
+         * unsubscribe();
+         */
+        <TData>(liveObject: LiveObject<TData>, callback: (updates: StorageUpdate[]) => void, options: {
+            isDeep: true;
+        }): () => void;
+        /**
+         * Subscribes to changes made on a {@link LiveList} and all the nested data structures. Returns an unsubscribe function.
+         * In a future version, we will also expose what exactly changed in the {@link LiveList}.
+         *
+         * @param listener the callback this called when the {@link LiveList} changes.
+         *
+         * @returns Unsubscribe function.
+         *
+         * @example
+         * const liveList = new LiveList();
+         * const unsubscribe = room.subscribe(liveList, (liveList) => { }, { isDeep: true });
+         * unsubscribe();
+         */
+        <TItem>(liveList: LiveList<TItem>, callback: (updates: StorageUpdate[]) => void, options: {
+            isDeep: true;
+        }): () => void;
+    };
+    /**
+     * Room's history contains functions that let you undo and redo operation made on by the current client on the presence and storage.
+     */
+    history: {
+        /**
+         * Undoes the last operation executed by the current client.
+         * It does not impact operations made by other clients.
+         *
+         * @example
+         * room.updatePresence({ selectedId: "xxx" }, { addToHistory: true });
+         * room.updatePresence({ selectedId: "yyy" }, { addToHistory: true });
+         * room.history.undo();
+         * // room.getPresence() equals { selectedId: "xxx" }
+         */
+        undo: () => void;
+        /**
+         * Redoes the last operation executed by the current client.
+         * It does not impact operations made by other clients.
+         *
+         * @example
+         * room.updatePresence({ selectedId: "xxx" }, { addToHistory: true });
+         * room.updatePresence({ selectedId: "yyy" }, { addToHistory: true });
+         * room.history.undo();
+         * // room.getPresence() equals { selectedId: "xxx" }
+         * room.history.redo();
+         * // room.getPresence() equals { selectedId: "yyy" }
+         */
+        redo: () => void;
+        /**
+         * All future modifications made on the Room will be merged together to create a single history item until resume is called.
+         *
+         * @example
+         * room.updatePresence({ cursor: { x: 0, y: 0 } }, { addToHistory: true });
+         * room.history.pause();
+         * room.updatePresence({ cursor: { x: 1, y: 1 } }, { addToHistory: true });
+         * room.updatePresence({ cursor: { x: 2, y: 2 } }, { addToHistory: true });
+         * room.history.resume();
+         * room.history.undo();
+         * // room.getPresence() equals { cursor: { x: 0, y: 0 } }
+         */
+        pause: () => void;
+        /**
+         * Resumes history. Modifications made on the Room are not merged into a single history item anymore.
+         *
+         * @example
+         * room.updatePresence({ cursor: { x: 0, y: 0 } }, { addToHistory: true });
+         * room.history.pause();
+         * room.updatePresence({ cursor: { x: 1, y: 1 } }, { addToHistory: true });
+         * room.updatePresence({ cursor: { x: 2, y: 2 } }, { addToHistory: true });
+         * room.history.resume();
+         * room.history.undo();
+         * // room.getPresence() equals { cursor: { x: 0, y: 0 } }
+         */
+        resume: () => void;
+    };
+    /**
+     * @deprecated use the callback returned by subscribe instead.
+     * See v0.13 release notes for more information.
+     * Will be removed in a future version.
+     */
+    unsubscribe: {
+        /**
+         * @deprecated use the callback returned by subscribe instead.
+         * See v0.13 release notes for more information.
+         * Will be removed in a future version.
+         */
+        <T extends Presence>(type: "my-presence", listener: MyPresenceCallback<T>): void;
+        /**
+         * @deprecated use the callback returned by subscribe instead.
+         * See v0.13 release notes for more information.
+         * Will be removed in a future version.
+         */
+        <T extends Presence>(type: "others", listener: OthersEventCallback<T>): void;
+        /**
+         * @deprecated use the callback returned by subscribe instead.
+         * See v0.13 release notes for more information.
+         * Will be removed in a future version.
          */
         (type: "event", listener: EventCallback): void;
         /**
-         * Unsubscribe to errors thrown in the room.
+         * @deprecated use the callback returned by subscribe instead.
+         * See v0.13 release notes for more information.
+         * Will be removed in a future version.
          */
         (type: "error", listener: ErrorCallback): void;
         /**
-         * Unsubscribe to connection state updates.
+         * @deprecated use the callback returned by subscribe instead.
+         * See v0.13 release notes for more information.
+         * Will be removed in a future version.
          */
         (type: "connection", listener: ConnectionCallback): void;
     };
@@ -237,7 +392,8 @@ export declare type Room = {
     getOthers: <T extends Presence>() => Others<T>;
     /**
      * Updates the presence of the current user. Only pass the properties you want to update. No need to send the full presence.
-     * @param {Partial<T>} overrides - A partial object that contains the properties you want to update.
+     * @param overrides A partial object that contains the properties you want to update.
+     * @param overrides Optional object to configure the behavior of updatePresence.
      *
      * @example
      * room.updatePresence({ x: 0 });
@@ -246,10 +402,15 @@ export declare type Room = {
      * const presence = room.getPresence();
      * // presence is equivalent to { x: 0, y: 0 }
      */
-    updatePresence: <T extends Presence>(overrides: Partial<T>) => void;
+    updatePresence: <T extends Presence>(overrides: Partial<T>, options?: {
+        /**
+         * Whether or not the presence should have an impact on the undo/redo history.
+         */
+        addToHistory: boolean;
+    }) => void;
     /**
-     * Broadcast an event to other users in the room. Event broadcasted to the room can be listened with {@link Room.subscribe}("event").
-     * @param {any} event - the event to broadcast. Should be serializable to JSON
+     * Broadcasts an event to other users in the room. Event broadcasted to the room can be listened with {@link Room.subscribe}("event").
+     * @param {any} event the event to broadcast. Should be serializable to JSON
      *
      * @example
      * // On client A
@@ -263,10 +424,29 @@ export declare type Room = {
      * });
      */
     broadcastEvent: (event: any) => void;
+    /**
+     * Get the room's storage asynchronously.
+     * The storage's root is a {@link LiveObject}.
+     *
+     * @example
+     * const { root } = await room.getStorage();
+     */
     getStorage: <TRoot>() => Promise<{
         root: LiveObject<TRoot>;
     }>;
-    undo: () => void;
-    redo: () => void;
+    /**
+     * Batches modifications made during the given function.
+     * All the modifications are sent to other clients in a single message.
+     * All the subscribers are called only after the batch is over.
+     * All the modifications are merged in a single history item (undo/redo).
+     *
+     * @example
+     * const { root } = await room.getStorage();
+     * room.batch(() => {
+     *   root.set("x", 0);
+     *   room.updatePresence({ cursor: { x: 100, y: 100 }});
+     * });
+     */
+    batch: (fn: () => void) => void;
 };
 export {};

package/lib/esm/utils.d.ts

@@ -1 +1,8 @@
+import { AbstractCrdt, Doc } from "./AbstractCrdt";
+import { SerializedCrdtWithId } from "./live";
 export declare function remove<T>(array: T[], item: T): void;
+export declare function isSameNodeOrChildOf(node: AbstractCrdt, parent: AbstractCrdt): boolean;
+export declare function deserialize(entry: SerializedCrdtWithId, parentToChildren: Map<string, SerializedCrdtWithId[]>, doc: Doc): AbstractCrdt;
+export declare function isCrdt(obj: any): obj is AbstractCrdt;
+export declare function selfOrRegisterValue(obj: AbstractCrdt): any;
+export declare function selfOrRegister(obj: any): AbstractCrdt;

package/lib/esm/utils.js

@@ -1,3 +1,8 @@
+import { CrdtType, } from "./live";
+import { LiveList } from "./LiveList";
+import { LiveMap } from "./LiveMap";
+import { LiveObject } from "./LiveObject";
+import { LiveRegister } from "./LiveRegister";
 export function remove(array, item) {
     for (let i = 0; i < array.length; i++) {
         if (array[i] === item) {
@@ -6,3 +11,56 @@ export function remove(array, item) {
         }
     }
 }
+export function isSameNodeOrChildOf(node, parent) {
+    if (node === parent) {
+        return true;
+    }
+    if (node._parent) {
+        return isSameNodeOrChildOf(node._parent, parent);
+    }
+    return false;
+}
+export function deserialize(entry, parentToChildren, doc) {
+    switch (entry[1].type) {
+        case CrdtType.Object: {
+            return LiveObject._deserialize(entry, parentToChildren, doc);
+        }
+        case CrdtType.List: {
+            return LiveList._deserialize(entry, parentToChildren, doc);
+        }
+        case CrdtType.Map: {
+            return LiveMap._deserialize(entry, parentToChildren, doc);
+        }
+        case CrdtType.Register: {
+            return LiveRegister._deserialize(entry, parentToChildren, doc);
+        }
+        default: {
+            throw new Error("Unexpected CRDT type");
+        }
+    }
+}
+export function isCrdt(obj) {
+    return (obj instanceof LiveObject ||
+        obj instanceof LiveMap ||
+        obj instanceof LiveList ||
+        obj instanceof LiveRegister);
+}
+export function selfOrRegisterValue(obj) {
+    if (obj instanceof LiveRegister) {
+        return obj.data;
+    }
+    return obj;
+}
+export function selfOrRegister(obj) {
+    if (obj instanceof LiveObject ||
+        obj instanceof LiveMap ||
+        obj instanceof LiveList) {
+        return obj;
+    }
+    else if (obj instanceof LiveRegister) {
+        throw new Error("Internal error. LiveRegister should not be created from selfOrRegister");
+    }
+    else {
+        return new LiveRegister(obj);
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@liveblocks/client",
-  "version": "0.12.2",
+  "version": "0.13.1",
   "description": "",
   "main": "./lib/cjs/index.js",
   "module": "./lib/esm/index.js",
@@ -19,8 +19,8 @@
   "scripts": {
     "build-and-pack": "npm run build && npm pack",
     "build": "npm run build:esm && npm run build:cjs",
-    "build:esm": "tsc -p tsconfig.json && rm ./lib/esm/*.test.js && rm ./lib/esm/*.test.d.ts",
-    "build:cjs": "tsc -p tsconfig-cjs.json && rm ./lib/cjs/*.test.js && rm ./lib/cjs/*.test.d.ts",
+    "build:esm": "tsc -p tsconfig-esm.json",
+    "build:cjs": "tsc -p tsconfig-cjs.json",
     "test": "jest --watch"
   },
   "license": "Apache-2.0",