@liveblocks/client 0.16.10 → 0.16.13

package/shared.d.ts

@@ -1,105 +1,37 @@
-/**
- * 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;
+declare type ApplyResult = {
+    reverse: Op[];
+    modified: StorageUpdate;
+} | {
+    modified: false;
 };
-/**
- * Alternative to JSON.parse() that will not throw in production. If the passed
- * string cannot be parsed, this will return `undefined`.
- */
-declare function parseJson(rawMessage: 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])[] | undefined);
-    /**
-     * @deprecated Please call as `new LiveMap()` or `new LiveMap([])` instead.
-     */
-    constructor(entries: null);
-    /**
-     * 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;
+interface Doc {
+    roomId: string;
+    generateId: () => string;
+    generateOpId: () => string;
+    getItem: (id: string) => LiveNode | undefined;
+    addItem: (id: string, liveItem: LiveNode) => void;
+    deleteItem: (id: string) => void;
+    /**
+     * Dispatching has three responsibilities:
+     * - Sends serialized ops to the WebSocket servers
+     * - Add reverse operations to the undo/redo stack
+     * - Notify room subscribers with updates (in-client, no networking)
+     */
+    dispatch: (ops: Op[], reverseOps: Op[], storageUpdates: Map<string, StorageUpdate>) => void;
+}
+declare abstract class AbstractCrdt {
+    private __doc?;
+    private __id?;
+    private _parent;
+    get roomId(): string | null;
 }
-
-/**
- * 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 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 {
+declare class LiveList<TItem extends Lson> extends AbstractCrdt {
     private _items;
+    private _implicitlyDeletedItems;
     constructor(items?: TItem[]);
     /**
      * Returns the number of elements.
@@ -197,6 +129,303 @@ declare class LiveList<TItem extends Lson = Lson> extends AbstractCrdt {
     [Symbol.iterator](): IterableIterator<TItem>;
 }
 
+/**
+ * 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 Lson> extends AbstractCrdt {
+    private _map;
+    constructor(entries?: readonly (readonly [TKey, TValue])[] | undefined);
+    /**
+     * @deprecated Please call as `new LiveMap()` or `new LiveMap([])` instead.
+     */
+    constructor(entries: null);
+    /**
+     * 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;
+}
+
+/**
+ * The LiveObject class is similar to a JavaScript object 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 LiveObject<O extends LsonObject> extends AbstractCrdt {
+    private _map;
+    private _propToLastUpdate;
+    constructor(obj?: O);
+    private _applyUpdate;
+    private _applyDeleteObjectKey;
+    /**
+     * Transform the LiveObject into a javascript object
+     */
+    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 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 O>(key: TKey): O[TKey];
+    /**
+     * Deletes a key from the LiveObject
+     * @param key The key of the property to delete
+     */
+    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<O>): void;
+}
+
+/**
+ * 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;
+};
+
+/**
+ * INTERNAL
+ */
+declare class LiveRegister<TValue extends Json> extends AbstractCrdt {
+    _data: TValue;
+    constructor(data: TValue);
+    get data(): TValue;
+    /**
+     * INTERNAL
+     */
+    static _deserialize([id, item]: IdTuple<SerializedRegister>, _parentToChildren: ParentToChildNodeMap, doc: Doc): LiveRegister<Json>;
+    /**
+     * INTERNAL
+     */
+    _serialize(parentId: string, parentKey: string, doc?: Doc): Op[];
+    /**
+     * INTERNAL
+     */
+    _toSerializedCrdt(): SerializedRegister;
+    _attachChild(_op: CreateChildOp): ApplyResult;
+    _detachChild(_crdt: LiveNode): ApplyResult;
+    _apply(op: Op, isLocal: boolean): ApplyResult;
+}
+
+declare type LiveStructure = LiveObject<LsonObject> | LiveList<Lson> | LiveMap<string, Lson>;
+/**
+ * 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 | LiveStructure;
+/**
+ * LiveNode is the internal tree for managing Live data structures. The key
+ * difference with Lson is that all the Json values get represented in
+ * a LiveRegister node.
+ */
+declare type LiveNode = LiveStructure | LiveRegister<Json>;
+/**
+ * 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 type LsonObject = {
+    [key: string]: Lson | undefined;
+};
+
+declare enum OpCode {
+    INIT = 0,
+    SET_PARENT_KEY = 1,
+    CREATE_LIST = 2,
+    UPDATE_OBJECT = 3,
+    CREATE_OBJECT = 4,
+    DELETE_CRDT = 5,
+    DELETE_OBJECT_KEY = 6,
+    CREATE_MAP = 7,
+    CREATE_REGISTER = 8
+}
+/**
+ * These operations are the payload for {@link UpdateStorageServerMsg} messages
+ * only.
+ */
+declare type Op = CreateOp | UpdateObjectOp | DeleteCrdtOp | SetParentKeyOp | DeleteObjectKeyOp;
+declare type CreateOp = CreateRootObjectOp | CreateChildOp;
+declare type CreateChildOp = CreateObjectOp | CreateRegisterOp | CreateMapOp | CreateListOp;
+declare type UpdateObjectOp = {
+    opId?: string;
+    id: string;
+    type: OpCode.UPDATE_OBJECT;
+    data: Partial<JsonObject>;
+};
+declare type CreateObjectOp = {
+    opId?: string;
+    id: string;
+    intent?: "set";
+    deletedId?: string;
+    type: OpCode.CREATE_OBJECT;
+    parentId: string;
+    parentKey: string;
+    data: JsonObject;
+};
+declare type CreateRootObjectOp = Resolve<Omit<CreateObjectOp, "parentId" | "parentKey"> & {
+    parentId?: never;
+    parentKey?: never;
+}>;
+declare type CreateListOp = {
+    opId?: string;
+    id: string;
+    intent?: "set";
+    deletedId?: string;
+    type: OpCode.CREATE_LIST;
+    parentId: string;
+    parentKey: string;
+};
+declare type CreateMapOp = {
+    opId?: string;
+    id: string;
+    intent?: "set";
+    deletedId?: string;
+    type: OpCode.CREATE_MAP;
+    parentId: string;
+    parentKey: string;
+};
+declare type CreateRegisterOp = {
+    opId?: string;
+    id: string;
+    intent?: "set";
+    deletedId?: string;
+    type: OpCode.CREATE_REGISTER;
+    parentId: string;
+    parentKey: string;
+    data: Json;
+};
+declare type DeleteCrdtOp = {
+    opId?: string;
+    id: string;
+    type: OpCode.DELETE_CRDT;
+};
+declare type SetParentKeyOp = {
+    opId?: string;
+    id: string;
+    type: OpCode.SET_PARENT_KEY;
+    parentKey: string;
+};
+declare type DeleteObjectKeyOp = {
+    opId?: string;
+    id: string;
+    type: OpCode.DELETE_OBJECT_KEY;
+    key: string;
+};
+
+declare type IdTuple<T> = [id: string, value: T];
+declare enum CrdtType {
+    OBJECT = 0,
+    LIST = 1,
+    MAP = 2,
+    REGISTER = 3
+}
+declare type SerializedCrdt = SerializedRootObject | SerializedChild;
+declare type SerializedChild = SerializedObject | SerializedList | SerializedMap | SerializedRegister;
+declare type SerializedRootObject = {
+    type: CrdtType.OBJECT;
+    data: JsonObject;
+    parentId?: never;
+    parentKey?: never;
+};
+declare type SerializedObject = {
+    type: CrdtType.OBJECT;
+    parentId: string;
+    parentKey: string;
+    data: JsonObject;
+};
+declare type SerializedList = {
+    type: CrdtType.LIST;
+    parentId: string;
+    parentKey: string;
+};
+declare type SerializedMap = {
+    type: CrdtType.MAP;
+    parentId: string;
+    parentKey: string;
+};
+declare type SerializedRegister = {
+    type: CrdtType.REGISTER;
+    parentId: string;
+    parentKey: string;
+    data: Json;
+};
+declare function isRootCrdt(crdt: SerializedCrdt): crdt is SerializedRootObject;
+declare function isChildCrdt(crdt: SerializedCrdt): crdt is SerializedChild;
+
+/**
+ * Lookup table for nodes (= SerializedCrdt values) by their IDs.
+ */
+declare type NodeMap = Map<string, // Node ID
+SerializedCrdt>;
+/**
+ * Reverse lookup table for all child nodes (= list of SerializedCrdt values)
+ * by their parent node's IDs.
+ */
+declare type ParentToChildNodeMap = Map<string, // Parent's node ID
+IdTuple<SerializedChild>[]>;
+
 /**
  * This helper type is effectively a no-op, but will force TypeScript to
  * "evaluate" any named helper types in its definition. This can sometimes make
@@ -219,7 +448,7 @@ declare class LiveList<TItem extends Lson = Lson> extends AbstractCrdt {
  * This trick comes from:
  * https://effectivetypescript.com/2022/02/25/gentips-4-display/
  */
-declare type Resolve<T> = T extends Function ? T : {
+declare type Resolve<T> = T extends (...args: any[]) => any ? T : {
     [K in keyof T]: T[K];
 };
 declare type MyPresenceCallback<T extends Presence = Presence> = (me: T) => void;
@@ -431,10 +660,10 @@ interface History {
      * It does not impact operations made by other clients.
      *
      * @example
-     * room.updatePresence({ selectedId: "xxx" }, { addToHistory: true });
-     * room.updatePresence({ selectedId: "yyy" }, { addToHistory: true });
+     * room.updatePresence({ selectedId: "xx" }, { addToHistory: true });
+     * room.updatePresence({ selectedId: "yy" }, { addToHistory: true });
      * room.history.undo();
-     * // room.getPresence() equals { selectedId: "xxx" }
+     * // room.getPresence() equals { selectedId: "xx" }
      */
     undo: () => void;
     /**
@@ -442,12 +671,12 @@ interface History {
      * It does not impact operations made by other clients.
      *
      * @example
-     * room.updatePresence({ selectedId: "xxx" }, { addToHistory: true });
-     * room.updatePresence({ selectedId: "yyy" }, { addToHistory: true });
+     * room.updatePresence({ selectedId: "xx" }, { addToHistory: true });
+     * room.updatePresence({ selectedId: "yy" }, { addToHistory: true });
      * room.history.undo();
-     * // room.getPresence() equals { selectedId: "xxx" }
+     * // room.getPresence() equals { selectedId: "xx" }
      * room.history.redo();
-     * // room.getPresence() equals { selectedId: "yyy" }
+     * // room.getPresence() equals { selectedId: "yy" }
      */
     redo: () => void;
     /**
@@ -620,43 +849,6 @@ declare type Room = {
      * Room's history contains functions that let you undo and redo operation made on by the current client on the presence and storage.
      */
     history: History;
-    /**
-     * @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;
-        /**
-         * @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;
-        /**
-         * @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;
-    };
     /**
      * Gets the current user.
      * Returns null if not it is not yet connected to the room.
@@ -738,51 +930,15 @@ declare type Room = {
      */
     batch: (fn: () => void) => void;
 };
-
-declare abstract class AbstractCrdt {
-    private __parent?;
-    private __doc?;
-    private __id?;
-    private __parentKey?;
-    get roomId(): string | null;
-}
-
-/**
- * The LiveObject class is similar to a JavaScript object 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 LiveObject<O extends LsonObject = LsonObject> extends AbstractCrdt {
-    private _map;
-    private _propToLastUpdate;
-    constructor(obj?: O);
-    private _applyUpdate;
-    private _applyDeleteObjectKey;
-    /**
-     * Transform the LiveObject into a javascript object
-     */
-    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 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 O>(key: TKey): O[TKey];
-    /**
-     * Deletes a key from the LiveObject
-     * @param key The key of the property to delete
-     */
-    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<O>): void;
+declare enum WebsocketCloseCodes {
+    CLOSE_ABNORMAL = 1006,
+    INVALID_MESSAGE_FORMAT = 4000,
+    NOT_ALLOWED = 4001,
+    MAX_NUMBER_OF_MESSAGES_PER_SECONDS = 4002,
+    MAX_NUMBER_OF_CONCURRENT_CONNECTIONS = 4003,
+    MAX_NUMBER_OF_MESSAGES_PER_DAY_PER_APP = 4004,
+    MAX_NUMBER_OF_CONCURRENT_CONNECTIONS_PER_ROOM = 4005,
+    CLOSE_WITHOUT_RETRY = 4999
 }
 
-export { AbstractCrdt as A, BroadcastOptions as B, ClientOptions as C, History as H, Json as J, LiveObject as L, Others as O, Presence as P, Room as R, StorageUpdate as S, User as U, Client as a, LiveMap as b, LiveList as c, JsonObject as d, Lson as e, LsonObject as f, Resolve as g, RoomInitializers as h, parseJson as p };
+export { SerializedRootObject as A, BroadcastOptions as B, ClientOptions as C, DeleteCrdtOp as D, SetParentKeyOp as E, UpdateObjectOp as F, CrdtType as G, History as H, IdTuple as I, Json as J, OpCode as K, LiveList as L, isChildCrdt as M, NodeMap as N, Others as O, Presence as P, isRootCrdt as Q, Room as R, StorageUpdate as S, User as U, WebsocketCloseCodes as W, Client as a, LiveMap as b, LiveObject as c, JsonObject as d, LiveStructure as e, Lson as f, LsonObject as g, Op as h, SerializedCrdt as i, CreateChildOp as j, CreateListOp as k, CreateMapOp as l, CreateObjectOp as m, CreateOp as n, CreateRegisterOp as o, CreateRootObjectOp as p, DeleteObjectKeyOp as q, LiveNode as r, ParentToChildNodeMap as s, Resolve as t, RoomInitializers as u, SerializedChild as v, SerializedList as w, SerializedMap as x, SerializedObject as y, SerializedRegister as z };