@liveblocks/client 0.17.0-test1 → 0.17.1

package/shared.d.ts

@@ -1,34 +1,4 @@
-declare type ApplyResult =
-  | {
-      reverse: Op[];
-      modified: StorageUpdate;
-    }
-  | {
-      modified: false;
-    };
-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;
 }
 
@@ -36,9 +6,6 @@ declare abstract class AbstractCrdt {
  * The LiveList class represents an ordered collection of items that is synchronized across clients.
  */
 declare class LiveList<TItem extends Lson> extends AbstractCrdt {
-  private _items;
-  private _implicitlyDeletedItems;
-  private _unacknowledgedSets;
   constructor(items?: TItem[]);
   /**
    * Returns the number of elements.
@@ -145,7 +112,6 @@ 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.
@@ -209,16 +175,7 @@ declare class LiveMap<
  * 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);
-  _serialize(
-    parentId?: undefined,
-    parentKey?: undefined,
-    doc?: Doc
-  ): CreateOp[];
-  private _applyUpdate;
-  private _applyDeleteObjectKey;
   /**
    * Transform the LiveObject into a javascript object
    */
@@ -266,36 +223,24 @@ declare function isJsonScalar(data: Json): data is JsonScalar;
 declare function isJsonArray(data: Json): data is JsonArray;
 declare function isJsonObject(data: Json): data is JsonObject;
 
+declare type BaseUserMeta = {
+  /**
+   * The id of the user that has been set in the authentication endpoint.
+   * Useful to get additional information about the connected user.
+   */
+  id?: string;
+  /**
+   * Additional user information that has been set in the authentication endpoint.
+   */
+  info?: Json;
+};
+
 /**
  * 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
-  ): CreateRegisterOp[];
-  /**
-   * INTERNAL
-   */
-  _toSerializedCrdt(): SerializedRegister;
-  _attachChild(_op: CreateChildOp): ApplyResult;
-  _detachChild(_crdt: LiveNode): ApplyResult;
-  _apply(op: Op, isLocal: boolean): ApplyResult;
 }
 
 declare type LiveStructure =
@@ -321,163 +266,6 @@ 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 = {
-  opId?: string;
-  id: string;
-  type: OpCode.CREATE_OBJECT;
-  data: JsonObject;
-  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
@@ -508,16 +296,19 @@ declare type Resolve<T> = T extends (...args: unknown[]) => unknown
 declare type MyPresenceCallback<TPresence extends JsonObject> = (
   me: TPresence
 ) => void;
-declare type OthersEventCallback<TPresence extends JsonObject> = (
-  others: Others<TPresence>,
-  event: OthersEvent<TPresence>
+declare type OthersEventCallback<
+  TPresence extends JsonObject,
+  TUserMeta extends BaseUserMeta
+> = (
+  others: Others<TPresence, TUserMeta>,
+  event: OthersEvent<TPresence, TUserMeta>
 ) => void;
-declare type EventCallback = ({
+declare type EventCallback<TRoomEvent extends Json> = ({
   connectionId,
   event,
 }: {
   connectionId: number;
-  event: Json;
+  event: TRoomEvent;
 }) => void;
 declare type ErrorCallback = (error: Error) => void;
 declare type ConnectionCallback = (state: ConnectionState) => void;
@@ -602,6 +393,7 @@ declare type StorageUpdate =
   | LiveMapUpdates<string, Lson>
   | LiveObjectUpdates<LsonObject>
   | LiveListUpdates<Lson>;
+declare type StorageCallback = (updates: StorageUpdate[]) => void;
 declare type RoomInitializers<
   TPresence extends JsonObject,
   TStorage extends LsonObject
@@ -632,18 +424,28 @@ declare type Client = {
    *
    * @param roomId The id of the room
    */
-  getRoom<TPresence extends JsonObject, TStorage extends LsonObject>(
+  getRoom<
+    TPresence extends JsonObject,
+    TStorage extends LsonObject = LsonObject,
+    TUserMeta extends BaseUserMeta = BaseUserMeta,
+    TRoomEvent extends Json = never
+  >(
     roomId: string
-  ): Room<TPresence, TStorage> | null;
+  ): Room<TPresence, TStorage, TUserMeta, TRoomEvent> | null;
   /**
    * Enters a room and returns it.
    * @param roomId The id of the room
    * @param options Optional. You can provide initializers for the Presence or Storage when entering the Room.
    */
-  enter<TPresence extends JsonObject, TStorage extends LsonObject>(
+  enter<
+    TPresence extends JsonObject,
+    TStorage extends LsonObject = LsonObject,
+    TUserMeta extends BaseUserMeta = BaseUserMeta,
+    TRoomEvent extends Json = never
+  >(
     roomId: string,
     options?: RoomInitializers<TPresence, TStorage>
-  ): Room<TPresence, TStorage>;
+  ): Room<TPresence, TStorage, TUserMeta, TRoomEvent>;
   /**
    * Leaves a room.
    * @param roomId The id of the room
@@ -653,7 +455,7 @@ declare type Client = {
 /**
  * Represents all the other users connected in the room. Treated as immutable.
  */
-interface Others<TPresence extends JsonObject> {
+interface Others<TPresence extends JsonObject, TUserMeta extends BaseUserMeta> {
   /**
    * Number of other users in the room.
    */
@@ -661,20 +463,23 @@ interface Others<TPresence extends JsonObject> {
   /**
    * Returns a new Iterator object that contains the users.
    */
-  [Symbol.iterator](): IterableIterator<User<TPresence>>;
+  [Symbol.iterator](): IterableIterator<User<TPresence, TUserMeta>>;
   /**
    * Returns the array of connected users in room.
    */
-  toArray(): User<TPresence>[];
+  toArray(): User<TPresence, TUserMeta>[];
   /**
    * This function let you map over the connected users in the room.
    */
-  map<U>(callback: (user: User<TPresence>) => U): U[];
+  map<U>(callback: (user: User<TPresence, TUserMeta>) => U): U[];
 }
 /**
  * Represents a user connected in a room. Treated as immutable.
  */
-declare type User<TPresence extends JsonObject> = {
+declare type User<
+  TPresence extends JsonObject,
+  TUserMeta extends BaseUserMeta
+> = {
   /**
    * The connection id of the user. It is unique and increment at every new connection.
    */
@@ -683,11 +488,11 @@ declare type User<TPresence extends JsonObject> = {
    * The id of the user that has been set in the authentication endpoint.
    * Useful to get additional information about the connected user.
    */
-  readonly id?: string;
+  readonly id: TUserMeta["id"];
   /**
    * Additional user information that has been set in the authentication endpoint.
    */
-  readonly info?: any;
+  readonly info: TUserMeta["info"];
   /**
    * The user presence.
    */
@@ -713,15 +518,26 @@ declare type AuthEndpointCallback = (room: string) => Promise<{
   token: string;
 }>;
 declare type AuthEndpoint = string | AuthEndpointCallback;
+declare type Polyfills = {
+  atob?: (data: string) => string;
+  fetch?: typeof fetch;
+  WebSocket?: any;
+};
 /**
  * The authentication endpoint that is called to ensure that the current user has access to a room.
  * Can be an url or a callback if you need to add additional headers.
  */
 declare type ClientOptions = {
   throttle?: number;
-  fetchPolyfill?: typeof fetch;
-  WebSocketPolyfill?: any;
-  atobPolyfill?: (data: string) => string;
+  polyfills?: Polyfills;
+  /**
+   * Backward-compatible way to set `polyfills.fetch`.
+   */
+  fetchPolyfill?: Polyfills["fetch"];
+  /**
+   * Backward-compatible way to set `polyfills.WebSocket`.
+   */
+  WebSocketPolyfill?: Polyfills["WebSocket"];
 } & (
   | {
       publicApiKey: string;
@@ -743,18 +559,21 @@ declare type Connection =
       userInfo?: Json;
     };
 declare type ConnectionState = Connection["state"];
-declare type OthersEvent<TPresence extends JsonObject> =
+declare type OthersEvent<
+  TPresence extends JsonObject,
+  TUserMeta extends BaseUserMeta
+> =
   | {
       type: "leave";
-      user: User<TPresence>;
+      user: User<TPresence, TUserMeta>;
     }
   | {
       type: "enter";
-      user: User<TPresence>;
+      user: User<TPresence, TUserMeta>;
     }
   | {
       type: "update";
-      user: User<TPresence>;
+      user: User<TPresence, TUserMeta>;
       updates: Partial<TPresence>;
     }
   | {
@@ -812,7 +631,12 @@ interface History {
    */
   resume: () => void;
 }
-declare type Room<TPresence extends JsonObject, TStorage extends LsonObject> = {
+declare type Room<
+  TPresence extends JsonObject,
+  TStorage extends LsonObject,
+  TUserMeta extends BaseUserMeta,
+  TRoomEvent extends Json
+> = {
   /**
    * The id of the room.
    */
@@ -840,7 +664,10 @@ declare type Room<TPresence extends JsonObject, TStorage extends LsonObject> = {
      *   // Do something
      * });
      */
-    (type: "others", listener: OthersEventCallback<TPresence>): () => void;
+    (
+      type: "others",
+      listener: OthersEventCallback<TPresence, TUserMeta>
+    ): () => void;
     /**
      * Subscribe to events broadcasted by {@link Room.broadcastEvent}
      *
@@ -851,7 +678,7 @@ declare type Room<TPresence extends JsonObject, TStorage extends LsonObject> = {
      *   // Do something
      * });
      */
-    (type: "event", listener: EventCallback): () => void;
+    (type: "event", listener: EventCallback<TRoomEvent>): () => void;
     /**
      * Subscribe to errors thrown in the room.
      */
@@ -861,112 +688,40 @@ declare type Room<TPresence extends JsonObject, TStorage extends LsonObject> = {
      */
     (type: "connection", listener: ConnectionCallback): () => void;
     /**
-     * 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}.
+     * Subscribes to changes made on a Live structure. Returns an unsubscribe function.
+     * In a future version, we will also expose what exactly changed in the Live structure.
      *
-     * @param listener the callback this called when the {@link LiveMap} changes.
+     * @param callback The callback this called when the Live structure changes.
      *
      * @returns Unsubscribe function.
      *
      * @example
-     * const liveMap = new LiveMap();
+     * const liveMap = new LiveMap();  // Could also be LiveList or LiveObject
      * const unsubscribe = room.subscribe(liveMap, (liveMap) => { });
      * unsubscribe();
      */
-    <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}.
-     *
-     * @param callback the callback this called when the {@link LiveObject} changes.
-     *
-     * @returns Unsubscribe function.
-     *
-     * @example
-     * const liveObject = new LiveObject();
-     * const unsubscribe = room.subscribe(liveObject, (liveObject) => { });
-     * unsubscribe();
-     */
-    <TData extends JsonObject>(
-      liveObject: LiveObject<TData>,
-      callback: (liveObject: LiveObject<TData>) => void
+    <L extends LiveStructure>(
+      liveStructure: L,
+      callback: (node: L) => 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}.
+     * Subscribes to changes made on a Live structure and all the nested data
+     * structures. Returns an unsubscribe function. In a future version, we
+     * will also expose what exactly changed in the Live structure.
      *
-     * @param callback the callback this called when the {@link LiveList} changes.
+     * @param callback The callback this called when the Live structure, or any
+     * of its nested values, changes.
      *
      * @returns Unsubscribe function.
      *
      * @example
-     * const liveList = new LiveList();
-     * const unsubscribe = room.subscribe(liveList, (liveList) => { });
+     * const liveMap = new LiveMap();  // Could also be LiveList or LiveObject
+     * const unsubscribe = room.subscribe(liveMap, (updates) => { }, { isDeep: true });
      * unsubscribe();
      */
-    <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}.
-     *
-     * @param callback 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 extends Lson>(
-      liveMap: LiveMap<TKey, TValue>,
-      callback: (updates: LiveMapUpdates<TKey, TValue>[]) => void,
-      options: {
-        isDeep: true;
-      }
-    ): () => void;
-    /**
-     * 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 callback the callback this called when the {@link LiveObject} changes.
-     *
-     * @returns Unsubscribe function.
-     *
-     * @example
-     * const liveObject = new LiveObject();
-     * const unsubscribe = room.subscribe(liveObject, (liveObject) => { }, { isDeep: true });
-     * unsubscribe();
-     */
-    <TData extends LsonObject>(
-      liveObject: LiveObject<TData>,
-      callback: (updates: LiveObjectUpdates<TData>[]) => 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 callback 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 extends Lson>(
-      liveList: LiveList<TItem>,
-      callback: (updates: LiveListUpdates<TItem>[]) => void,
+    <L extends LiveStructure>(
+      liveStructure: L,
+      callback: StorageCallback,
       options: {
         isDeep: true;
       }
@@ -983,7 +738,7 @@ declare type Room<TPresence extends JsonObject, TStorage extends LsonObject> = {
    * @example
    * const user = room.getSelf();
    */
-  getSelf(): User<TPresence> | null;
+  getSelf(): User<TPresence, TUserMeta> | null;
   /**
    * Gets the presence of the current user.
    *
@@ -997,7 +752,7 @@ declare type Room<TPresence extends JsonObject, TStorage extends LsonObject> = {
    * @example
    * const others = room.getOthers();
    */
-  getOthers: () => Others<TPresence>;
+  getOthers: () => Others<TPresence, TUserMeta>;
   /**
    * Updates the presence of the current user. Only pass the properties you want to update. No need to send the full presence.
    * @param overrides A partial object that contains the properties you want to update.
@@ -1034,7 +789,7 @@ declare type Room<TPresence extends JsonObject, TStorage extends LsonObject> = {
    *   }
    * });
    */
-  broadcastEvent: (event: Json, options?: BroadcastOptions) => void;
+  broadcastEvent: (event: TRoomEvent, options?: BroadcastOptions) => void;
   /**
    * Get the room's storage asynchronously.
    * The storage's root is a {@link LiveObject}.
@@ -1042,13 +797,7 @@ declare type Room<TPresence extends JsonObject, TStorage extends LsonObject> = {
    * @example
    * const { root } = await room.getStorage();
    */
-  getStorage: <
-    /**
-     * @deprecated This type argument is ignored. If you want to annotate this
-     * type manually, please annotate the Room instance instead.
-     */
-    _ = unknown
-  >() => Promise<{
+  getStorage: () => Promise<{
     root: LiveObject<TStorage>;
   }>;
   /**
@@ -1078,54 +827,29 @@ declare enum WebsocketCloseCodes {
 }
 
 export {
-  SerializedRootObject as A,
-  BroadcastOptions as B,
+  BaseUserMeta 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,
-  isJsonArray as M,
-  NodeMap as N,
   Others as O,
   Presence as P,
-  isJsonObject as Q,
   Room as R,
   StorageUpdate as S,
-  isJsonScalar as T,
   User as U,
-  isChildCrdt as V,
   WebsocketCloseCodes as W,
-  isRootCrdt as X,
   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,
+  BroadcastOptions as d,
+  JsonObject as e,
+  LiveStructure as f,
+  Lson as g,
+  LsonObject as h,
+  LiveNode as i,
+  Resolve as j,
+  RoomInitializers as k,
+  isJsonArray as l,
+  isJsonObject as m,
+  isJsonScalar as n,
 };