@liveblocks/client 0.15.11 → 0.16.2

package/{lib/index.d.ts → index.d.ts}

@@ -1,9 +1,97 @@
 /**
- * The LiveList class represents an ordered collection of items that is synchorinized across clients.
+ * Represents an indefinitely deep arbitrary JSON data structure. There are
+ * four types that make up the Json family:
+ *
+ * - Json         any legal JSON value
+ * - JsonScalar   any legal JSON leaf value (no lists or objects)
+ * - JsonArray    a JSON value whose outer type is an array
+ * - JsonObject   a JSON value whose outer type is an object
+ *
+ */
+declare type Json = JsonScalar | JsonArray | JsonObject;
+declare type JsonScalar = string | number | boolean | null;
+declare type JsonArray = Json[];
+declare type JsonObject = {
+    [key: string]: Json | undefined;
+};
+
+/**
+ * The LiveMap class is similar to a JavaScript Map that is synchronized on all clients.
+ * Keys should be a string, and values should be serializable to JSON.
+ * If multiple clients update the same property simultaneously, the last modification received by the Liveblocks servers is the winner.
+ */
+declare class LiveMap<TKey extends string = string, TValue extends Lson = Lson> extends AbstractCrdt {
+    private _map;
+    constructor(entries?: readonly (readonly [TKey, TValue])[] | null | undefined);
+    /**
+     * Returns a specified element from the LiveMap.
+     * @param key The key of the element to return.
+     * @returns The element associated with the specified key, or undefined if the key can't be found in the LiveMap.
+     */
+    get(key: TKey): TValue | undefined;
+    /**
+     * Adds or updates an element with a specified key and a value.
+     * @param key The key of the element to add. Should be a string.
+     * @param value The value of the element to add. Should be serializable to JSON.
+     */
+    set(key: TKey, value: TValue): void;
+    /**
+     * Returns the number of elements in the LiveMap.
+     */
+    get size(): number;
+    /**
+     * Returns a boolean indicating whether an element with the specified key exists or not.
+     * @param key The key of the element to test for presence.
+     */
+    has(key: TKey): boolean;
+    /**
+     * Removes the specified element by key.
+     * @param key The key of the element to remove.
+     * @returns true if an element existed and has been removed, or false if the element does not exist.
+     */
+    delete(key: TKey): boolean;
+    /**
+     * Returns a new Iterator object that contains the [key, value] pairs for each element.
+     */
+    entries(): IterableIterator<[TKey, TValue]>;
+    /**
+     * Same function object as the initial value of the entries method.
+     */
+    [Symbol.iterator](): IterableIterator<[TKey, TValue]>;
+    /**
+     * Returns a new Iterator object that contains the keys for each element.
+     */
+    keys(): IterableIterator<TKey>;
+    /**
+     * Returns a new Iterator object that contains the values for each element.
+     */
+    values(): IterableIterator<TValue>;
+    /**
+     * Executes a provided function once per each key/value pair in the Map object, in insertion order.
+     * @param callback Function to execute for each entry in the map.
+     */
+    forEach(callback: (value: TValue, key: TKey, map: LiveMap<TKey, TValue>) => void): void;
+}
+
+/**
+ * Think of Lson as a sibling of the Json data tree, except that the nested
+ * data structure can contain a mix of Json values and LiveStructure instances.
+ */
+declare type Lson = Json | LiveObject<LsonObject> | LiveList<Lson> | LiveMap<string, Lson>;
+/**
+ * A mapping of keys to Lson values. A Lson value is any valid JSON
+ * value or a Live storage data structure (LiveMap, LiveList, etc.)
  */
-declare class LiveList<T> extends AbstractCrdt {
+declare type LsonObject = {
+    [key: string]: Lson | undefined;
+};
+
+/**
+ * The LiveList class represents an ordered collection of items that is synchronized across clients.
+ */
+declare class LiveList<TItem extends Lson = Lson> extends AbstractCrdt {
     private _items;
-    constructor(items?: T[]);
+    constructor(items?: TItem[]);
     /**
      * Returns the number of elements.
      */
@@ -12,13 +100,13 @@ declare class LiveList<T> extends AbstractCrdt {
      * Adds one element to the end of the LiveList.
      * @param element The element to add to the end of the LiveList.
      */
-    push(element: T): void;
+    push(element: TItem): void;
     /**
      * Inserts one element at a specified index.
      * @param element The element to insert.
      * @param index The index at which you want to insert the element.
      */
-    insert(element: T, index: number): void;
+    insert(element: TItem, index: number): void;
     /**
      * Move one element from one index to another.
      * @param index The index of the element to move
@@ -31,137 +119,80 @@ declare class LiveList<T> extends AbstractCrdt {
      */
     delete(index: number): void;
     clear(): void;
+    set(index: number, item: TItem): void;
     /**
      * Returns an Array of all the elements in the LiveList.
      */
-    toArray(): T[];
+    toArray(): TItem[];
     /**
      * Tests whether all elements pass the test implemented by the provided function.
      * @param predicate Function to test for each element, taking two arguments (the element and its index).
      * @returns true if the predicate function returns a truthy value for every element. Otherwise, false.
      */
-    every(predicate: (value: T, index: number) => unknown): boolean;
+    every(predicate: (value: TItem, index: number) => unknown): boolean;
     /**
      * Creates an array with all elements that pass the test implemented by the provided function.
      * @param predicate Function to test each element of the LiveList. Return a value that coerces to true to keep the element, or to false otherwise.
      * @returns An array with the elements that pass the test.
      */
-    filter(predicate: (value: T, index: number) => unknown): T[];
+    filter(predicate: (value: TItem, index: number) => unknown): TItem[];
     /**
      * Returns the first element that satisfies the provided testing function.
      * @param predicate Function to execute on each value.
      * @returns The value of the first element in the LiveList that satisfies the provided testing function. Otherwise, undefined is returned.
      */
-    find(predicate: (value: T, index: number) => unknown): T | undefined;
+    find(predicate: (value: TItem, index: number) => unknown): TItem | undefined;
     /**
      * Returns the index of the first element in the LiveList that satisfies the provided testing function.
      * @param predicate Function to execute on each value until the function returns true, indicating that the satisfying element was found.
      * @returns The index of the first element in the LiveList that passes the test. Otherwise, -1.
      */
-    findIndex(predicate: (value: T, index: number) => unknown): number;
+    findIndex(predicate: (value: TItem, index: number) => unknown): number;
     /**
      * Executes a provided function once for each element.
      * @param callbackfn Function to execute on each element.
      */
-    forEach(callbackfn: (value: T, index: number) => void): void;
+    forEach(callbackfn: (value: TItem, index: number) => void): void;
     /**
      * Get the element at the specified index.
      * @param index The index on the element to get.
      * @returns The element at the specified index or undefined.
      */
-    get(index: number): T | undefined;
+    get(index: number): TItem | undefined;
     /**
      * Returns the first index at which a given element can be found in the LiveList, or -1 if it is not present.
      * @param searchElement Element to locate.
      * @param fromIndex The index to start the search at.
      * @returns The first index of the element in the LiveList; -1 if not found.
      */
-    indexOf(searchElement: T, fromIndex?: number): number;
+    indexOf(searchElement: TItem, fromIndex?: number): number;
     /**
      * Returns the last index at which a given element can be found in the LiveList, or -1 if it is not present. The LiveLsit is searched backwards, starting at fromIndex.
      * @param searchElement Element to locate.
      * @param fromIndex The index at which to start searching backwards.
      * @returns
      */
-    lastIndexOf(searchElement: T, fromIndex?: number): number;
+    lastIndexOf(searchElement: TItem, fromIndex?: number): number;
     /**
      * Creates an array populated with the results of calling a provided function on every element.
      * @param callback Function that is called for every element.
      * @returns An array with each element being the result of the callback function.
      */
-    map<U>(callback: (value: T, index: number) => U): U[];
+    map<U>(callback: (value: TItem, index: number) => U): U[];
     /**
      * Tests whether at least one element in the LiveList passes the test implemented by the provided function.
      * @param predicate Function to test for each element.
      * @returns true if the callback function returns a truthy value for at least one element. Otherwise, false.
      */
-    some(predicate: (value: T, index: number) => unknown): boolean;
-    [Symbol.iterator](): IterableIterator<T>;
-}
-
-/**
- * The LiveMap class is similar to a JavaScript Map that is synchronized on all clients.
- * Keys should be a string, and values should be serializable to JSON.
- * If multiple clients update the same property simultaneously, the last modification received by the Liveblocks servers is the winner.
- */
-declare class LiveMap<TKey extends string, TValue> extends AbstractCrdt {
-    private _map;
-    constructor(entries?: readonly (readonly [TKey, TValue])[] | null | undefined);
-    /**
-     * Returns a specified element from the LiveMap.
-     * @param key The key of the element to return.
-     * @returns The element associated with the specified key, or undefined if the key can't be found in the LiveMap.
-     */
-    get(key: TKey): TValue | undefined;
-    /**
-     * Adds or updates an element with a specified key and a value.
-     * @param key The key of the element to add. Should be a string.
-     * @param value The value of the element to add. Should be serializable to JSON.
-     */
-    set(key: TKey, value: TValue): void;
-    /**
-     * Returns the number of elements in the LiveMap.
-     */
-    get size(): number;
-    /**
-     * Returns a boolean indicating whether an element with the specified key exists or not.
-     * @param key The key of the element to test for presence.
-     */
-    has(key: TKey): boolean;
-    /**
-     * Removes the specified element by key.
-     * @param key The key of the element to remove.
-     * @returns true if an element existed and has been removed, or false if the element does not exist.
-     */
-    delete(key: TKey): boolean;
-    /**
-     * Returns a new Iterator object that contains the [key, value] pairs for each element.
-     */
-    entries(): IterableIterator<[string, TValue]>;
-    /**
-     * Same function object as the initial value of the entries method.
-     */
-    [Symbol.iterator](): IterableIterator<[string, TValue]>;
-    /**
-     * Returns a new Iterator object that contains the keys for each element.
-     */
-    keys(): IterableIterator<TKey>;
-    /**
-     * Returns a new Iterator object that contains the values for each element.
-     */
-    values(): IterableIterator<TValue>;
-    /**
-     * Executes a provided function once per each key/value pair in the Map object, in insertion order.
-     * @param callback Function to execute for each entry in the map.
-     */
-    forEach(callback: (value: TValue, key: TKey, map: LiveMap<TKey, TValue>) => void): void;
+    some(predicate: (value: TItem, index: number) => unknown): boolean;
+    [Symbol.iterator](): IterableIterator<TItem>;
 }
 
 declare type MyPresenceCallback<T extends Presence = Presence> = (me: T) => void;
 declare type OthersEventCallback<T extends Presence = Presence> = (others: Others<T>, event: OthersEvent<T>) => void;
 declare type EventCallback = ({ connectionId, event, }: {
     connectionId: number;
-    event: any;
+    event: Json;
 }) => void;
 declare type ErrorCallback = (error: Error) => void;
 declare type ConnectionCallback = (state: ConnectionState) => void;
@@ -170,22 +201,34 @@ declare type UpdateDelta = {
 } | {
     type: "delete";
 };
-declare type LiveMapUpdates<TKey extends string = string, TValue = any> = {
+/**
+ * A LiveMap notification that is sent in-client to any subscribers whenever
+ * one or more of the values inside the LiveMap instance have changed.
+ */
+declare type LiveMapUpdates<TKey extends string, TValue extends Lson> = {
     type: "LiveMap";
     node: LiveMap<TKey, TValue>;
-    updates: Record<TKey, UpdateDelta>;
+    updates: {
+        [key: string]: UpdateDelta;
+    };
 };
-declare type LiveObjectUpdateDelta<T> = Partial<{
-    [Property in keyof T]: UpdateDelta;
-}>;
-declare type LiveObjectUpdates<TData = any> = {
+declare type LiveObjectUpdateDelta<O extends {
+    [key: string]: unknown;
+}> = {
+    [K in keyof O]?: UpdateDelta | undefined;
+};
+/**
+ * A LiveObject notification that is sent in-client to any subscribers whenever
+ * one or more of the entries inside the LiveObject instance have changed.
+ */
+declare type LiveObjectUpdates<TData extends LsonObject> = {
     type: "LiveObject";
     node: LiveObject<TData>;
     updates: LiveObjectUpdateDelta<TData>;
 };
 declare type LiveListUpdateDelta = {
     index: number;
-    item: AbstractCrdt;
+    item: any;
     type: "insert";
 } | {
     index: number;
@@ -193,10 +236,18 @@ declare type LiveListUpdateDelta = {
 } | {
     index: number;
     previousIndex: number;
-    item: AbstractCrdt;
+    item: any;
     type: "move";
+} | {
+    index: number;
+    item: any;
+    type: "set";
 };
-declare type LiveListUpdates<TItem = any> = {
+/**
+ * A LiveList notification that is sent in-client to any subscribers whenever
+ * one or more of the items inside the LiveList instance have changed.
+ */
+declare type LiveListUpdates<TItem extends Lson> = {
     type: "LiveList";
     node: LiveList<TItem>;
     updates: LiveListUpdateDelta[];
@@ -209,7 +260,12 @@ declare type BroadcastOptions = {
      */
     shouldQueueEventIfNotReady: boolean;
 };
-declare type StorageUpdate = LiveMapUpdates | LiveObjectUpdates | LiveListUpdates;
+/**
+ * The payload of notifications sent (in-client) when LiveStructures change.
+ * Messages of this kind are not originating from the network, but are 100%
+ * in-client.
+ */
+declare type StorageUpdate = LiveMapUpdates<string, Lson> | LiveObjectUpdates<LsonObject> | LiveListUpdates<Lson>;
 declare type Client = {
     /**
      * Gets a room. Returns null if {@link Client.enter} has not been called previously.
@@ -309,6 +365,58 @@ declare type OthersEvent<T extends Presence = Presence> = {
 } | {
     type: "reset";
 };
+interface 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;
+}
 declare type Room = {
     /**
      * The id of the room.
@@ -370,7 +478,7 @@ declare type Room = {
          * const unsubscribe = room.subscribe(liveMap, (liveMap) => { });
          * unsubscribe();
          */
-        <TKey extends string, TValue>(liveMap: LiveMap<TKey, TValue>, listener: (liveMap: LiveMap<TKey, TValue>) => void): () => void;
+        <TKey extends string, TValue extends Lson>(liveMap: LiveMap<TKey, TValue>, listener: (liveMap: LiveMap<TKey, TValue>) => void): () => void;
         /**
          * 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}.
@@ -384,7 +492,7 @@ declare type Room = {
          * const unsubscribe = room.subscribe(liveObject, (liveObject) => { });
          * unsubscribe();
          */
-        <TData>(liveObject: LiveObject<TData>, callback: (liveObject: LiveObject<TData>) => void): () => void;
+        <TData extends JsonObject>(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}.
@@ -398,7 +506,7 @@ declare type Room = {
          * const unsubscribe = room.subscribe(liveList, (liveList) => { });
          * unsubscribe();
          */
-        <TItem>(liveList: LiveList<TItem>, callback: (liveList: LiveList<TItem>) => void): () => void;
+        <TItem extends Lson>(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}.
@@ -412,7 +520,7 @@ declare type Room = {
          * const unsubscribe = room.subscribe(liveMap, (liveMap) => { }, { isDeep: true });
          * unsubscribe();
          */
-        <TKey extends string, TValue>(liveMap: LiveMap<TKey, TValue>, callback: (updates: StorageUpdate[]) => void, options: {
+        <TKey extends string, TValue extends Lson>(liveMap: LiveMap<TKey, TValue>, callback: (updates: LiveMapUpdates<TKey, TValue>[]) => void, options: {
             isDeep: true;
         }): () => void;
         /**
@@ -428,7 +536,7 @@ declare type Room = {
          * const unsubscribe = room.subscribe(liveObject, (liveObject) => { }, { isDeep: true });
          * unsubscribe();
          */
-        <TData>(liveObject: LiveObject<TData>, callback: (updates: StorageUpdate[]) => void, options: {
+        <TData extends LsonObject>(liveObject: LiveObject<TData>, callback: (updates: LiveObjectUpdates<TData>[]) => void, options: {
             isDeep: true;
         }): () => void;
         /**
@@ -444,65 +552,14 @@ declare type Room = {
          * const unsubscribe = room.subscribe(liveList, (liveList) => { }, { isDeep: true });
          * unsubscribe();
          */
-        <TItem>(liveList: LiveList<TItem>, callback: (updates: StorageUpdate[]) => void, options: {
+        <TItem extends Lson>(liveList: LiveList<TItem>, callback: (updates: LiveListUpdates<TItem>[]) => 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;
-    };
+    history: History;
     /**
      * @deprecated use the callback returned by subscribe instead.
      * See v0.13 release notes for more information.
@@ -595,7 +652,7 @@ declare type Room = {
      *   }
      * });
      */
-    broadcastEvent: (event: any, options?: BroadcastOptions) => void;
+    broadcastEvent: (event: JsonObject, options?: BroadcastOptions) => void;
     /**
      * Get the room's storage asynchronously.
      * The storage's root is a {@link LiveObject}.
@@ -603,7 +660,7 @@ declare type Room = {
      * @example
      * const { root } = await room.getStorage();
      */
-    getStorage: <TRoot>() => Promise<{
+    getStorage: <TRoot extends LsonObject>() => Promise<{
         root: LiveObject<TRoot>;
     }>;
     /**
@@ -635,37 +692,37 @@ declare abstract class AbstractCrdt {
  * Keys should be a string, and values should be serializable to JSON.
  * If multiple clients update the same property simultaneously, the last modification received by the Liveblocks servers is the winner.
  */
-declare class LiveObject<T extends Record<string, any> = Record<string, any>> extends AbstractCrdt {
+declare class LiveObject<O extends LsonObject = LsonObject> extends AbstractCrdt {
     private _map;
     private _propToLastUpdate;
-    constructor(object?: T);
+    constructor(object?: O);
     private _applyUpdate;
     private _applyDeleteObjectKey;
     /**
      * Transform the LiveObject into a javascript object
      */
-    toObject(): T;
+    toObject(): O;
     /**
      * Adds or updates a property with a specified key and a value.
      * @param key The key of the property to add
      * @param value The value of the property to add
      */
-    set<TKey extends keyof T>(key: TKey, value: T[TKey]): void;
+    set<TKey extends keyof O>(key: TKey, value: O[TKey]): void;
     /**
      * Returns a specified property from the LiveObject.
      * @param key The key of the property to get
      */
-    get<TKey extends keyof T>(key: TKey): T[TKey];
+    get<TKey extends keyof O>(key: TKey): O[TKey];
     /**
      * Deletes a key from the LiveObject
      * @param key The key of the property to delete
      */
-    delete(key: keyof T): void;
+    delete(key: keyof O): void;
     /**
      * Adds or updates multiple properties at once with an object.
      * @param overrides The object used to overrides properties
      */
-    update(overrides: Partial<T>): void;
+    update(overrides: Partial<O>): void;
 }
 
 /**
@@ -695,4 +752,4 @@ declare class LiveObject<T extends Record<string, any> = Record<string, any>> ex
  */
 declare function createClient(options: ClientOptions): Client;
 
-export { BroadcastOptions, Client, LiveList, LiveMap, LiveObject, Others, Presence, Room, StorageUpdate, User, createClient };
+export { BroadcastOptions, Client, History, Json, JsonObject, LiveList, LiveMap, LiveObject, Lson, LsonObject, Others, Presence, Room, StorageUpdate, User, createClient };