@liveblocks/core 1.0.12 → 1.1.0-beta1

package/dist/index.d.ts

@@ -568,8 +568,23 @@ declare type BaseUserMeta = {
 declare type Callback<T> = (event: T) => void;
 declare type UnsubscribeCallback = () => void;
 declare type Observable<T> = {
+    /**
+     * Register a callback function to be called whenever the event source emits
+     * an event.
+     */
     subscribe(callback: Callback<T>): UnsubscribeCallback;
+    /**
+     * Register a one-time callback function to be called whenever the event
+     * source emits an event. After the event fires, the callback is
+     * auto-unsubscribed.
+     */
     subscribeOnce(callback: Callback<T>): UnsubscribeCallback;
+    /**
+     * Returns a promise that will resolve when an event is emitted by this
+     * event source. Optionally, specify a predicate that has to match. The first
+     * event matching that predicate will then resolve the promise.
+     */
+    waitUntil(predicate?: (event: T) => boolean): Promise<T>;
 };
 
 interface IWebSocketEvent {
@@ -621,6 +636,64 @@ declare enum WebsocketCloseCodes {
     CLOSE_WITHOUT_RETRY = 4999
 }
 
+/**
+ * Old connection statuses, here for backward-compatibility reasons only.
+ */
+declare type LegacyConnectionStatus = "closed" | "authenticating" | "connecting" | "open" | "unavailable" | "failed";
+/**
+ * Returns a human-readable status indicating the current connection status of
+ * a Room, as returned by `room.getStatus()`. Can be used to implement
+ * a connection status badge.
+ */
+declare type Status = "initial" | "connecting" | "connected" | "reconnecting" | "disconnected";
+/**
+ * Used to report about app-level reconnection issues.
+ *
+ * Normal (quick) reconnects won't be reported as a "lost connection". Instead,
+ * the application will only get an event if the reconnection attempts by the
+ * client are taking (much) longer than usual. Definitely a situation you want
+ * to inform your users about, for example, by throwing a toast message on
+ * screen, or show a "trying to reconnect" banner.
+ */
+declare type LostConnectionEvent = "lost" | "restored" | "failed";
+/**
+ * Arbitrary record that will be used as the authentication "token". It's the
+ * value that is returned by calling the authentication delegate, and will get
+ * passed to the connection factory delegate. This value will be remembered by
+ * the connection manager, but its value will not be interpreted, so it can be
+ * any value (except null).
+ */
+declare type BaseAuthResult = NonNullable<Json>;
+declare type Delegates<T extends BaseAuthResult> = {
+    authenticate: () => Promise<T>;
+    createSocket: (token: T) => IWebSocketInstance;
+};
+
+declare type AppOnlyAuthToken = {
+    appId: string;
+    roomId?: never;
+    scopes: string[];
+};
+declare type RoomAuthToken = {
+    appId: string;
+    roomId: string;
+    scopes: string[];
+    actor: number;
+    maxConnectionsPerRoom?: number;
+    info?: Json;
+    groupIds?: string[];
+} & ({
+    id: string;
+    anonymousId?: never;
+} | {
+    id?: never;
+    anonymousId: string;
+});
+declare type AuthToken = AppOnlyAuthToken | RoomAuthToken;
+declare function isAppOnlyAuthToken(data: JsonObject): data is AppOnlyAuthToken;
+declare function isRoomAuthToken(data: JsonObject): data is RoomAuthToken;
+declare function isAuthToken(data: JsonObject): data is AuthToken;
+
 declare type ReadonlyArrayWithLegacyMethods<T> = readonly T[] & {
     /**
      * @deprecated Prefer the normal .length property on arrays.
@@ -682,28 +755,6 @@ declare type CustomEvent<TRoomEvent extends Json> = {
     connectionId: number;
     event: TRoomEvent;
 };
-declare type Connection = {
-    status: "closed";
-} | {
-    status: "authenticating";
-} | {
-    status: "connecting";
-    id: number;
-    userId?: string;
-    userInfo?: Json;
-    isReadOnly: boolean;
-} | {
-    status: "open";
-    id: number;
-    userId?: string;
-    userInfo?: Json;
-    isReadOnly: boolean;
-} | {
-    status: "unavailable";
-} | {
-    status: "failed";
-};
-declare type ConnectionStatus = Connection["status"];
 declare type StorageStatus = "not-loaded" | "loading" | "synchronizing" | "synchronized";
 interface History {
     /**
@@ -840,12 +891,47 @@ declare type SubscribeFn<TPresence extends JsonObject, _TStorage extends LsonObj
      */
     (type: "error", listener: ErrorCallback): () => void;
     /**
-     * Subscribe to connection state updates.
+     * @deprecated This API will be removed in a future version of Liveblocks.
+     * Prefer using the newer `.subscribe('status')` API.
+     *
+     * We recommend making the following changes if you use these APIs:
+     *
+     *     OLD APIs                       NEW APIs
+     *     .getConnectionState()     -->  .getStatus()
+     *     .subscribe('connection')  -->  .subscribe('status')
+     *
+     *     OLD STATUSES         NEW STATUSES
+     *     closed          -->  initial
+     *     authenticating  -->  connecting
+     *     connecting      -->  connecting
+     *     open            -->  connected
+     *     unavailable     -->  reconnecting
+     *     failed          -->  disconnected
+     *
+     * Subscribe to legacy connection status updates.
+     *
+     * @returns Unsubscribe function.
+     *
+     */
+    (type: "connection", listener: Callback<LegacyConnectionStatus>): () => void;
+    /**
+     * Subscribe to connection status updates. The callback will be called any
+     * time the status changes.
      *
      * @returns Unsubscribe function.
      *
      */
-    (type: "connection", listener: Callback<ConnectionStatus>): () => void;
+    (type: "status", listener: Callback<Status>): () => void;
+    /**
+     * Subscribe to the exceptional event where reconnecting to the Liveblocks
+     * servers is taking longer than usual. This typically is a sign of a client
+     * that has lost internet connectivity.
+     *
+     * This isn't problematic (because the Liveblocks client is still trying to
+     * reconnect), but it's typically a good idea to inform users about it if
+     * the connection takes too long to recover.
+     */
+    (type: "lost-connection", listener: Callback<LostConnectionEvent>): () => void;
     /**
      * 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.
@@ -922,7 +1008,30 @@ declare type Room<TPresence extends JsonObject, TStorage extends LsonObject, TUs
      * metadata and connection ID (from the auth server).
      */
     isSelfAware(): boolean;
-    getConnectionState(): ConnectionStatus;
+    /**
+     * @deprecated This API will be removed in a future version of Liveblocks.
+     * Prefer using `.getStatus()` instead.
+     *
+     * We recommend making the following changes if you use these APIs:
+     *
+     *     OLD APIs                       NEW APIs
+     *     .getConnectionState()     -->  .getStatus()
+     *     .subscribe('connection')  -->  .subscribe('status')
+     *
+     *     OLD STATUSES         NEW STATUSES
+     *     closed          -->  initial
+     *     authenticating  -->  connecting
+     *     connecting      -->  connecting
+     *     open            -->  connected
+     *     unavailable     -->  reconnecting
+     *     failed          -->  disconnected
+     */
+    getConnectionState(): LegacyConnectionStatus;
+    /**
+     * Return the current connection status for this room. Can be used to display
+     * a status badge for your Liveblocks connection.
+     */
+    getStatus(): Status;
     readonly subscribe: SubscribeFn<TPresence, TStorage, TUserMeta, TRoomEvent>;
     /**
      * Room's history contains functions that let you undo and redo operation made on by the current client on the presence and storage.
@@ -1003,6 +1112,9 @@ declare type Room<TPresence extends JsonObject, TStorage extends LsonObject, TUs
      */
     getStorageSnapshot(): LiveObject<TStorage> | null;
     readonly events: {
+        readonly connection: Observable<LegacyConnectionStatus>;
+        readonly status: Observable<Status>;
+        readonly lostConnection: Observable<LostConnectionEvent>;
         readonly customEvent: Observable<{
             connectionId: number;
             event: TRoomEvent;
@@ -1013,12 +1125,12 @@ declare type Room<TPresence extends JsonObject, TStorage extends LsonObject, TUs
             event: OthersEvent<TPresence, TUserMeta>;
         }>;
         readonly error: Observable<Error>;
-        readonly connection: Observable<ConnectionStatus>;
         readonly storage: Observable<StorageUpdate[]>;
         readonly history: Observable<HistoryEvent>;
         /**
-         * Subscribe to the storage loaded event. Will fire at most once during the
-         * lifetime of a Room.
+         * Subscribe to the storage loaded event. Will fire any time a full Storage
+         * copy is downloaded. (This happens after the initial connect, and on
+         * every reconnect.)
          */
         readonly storageDidLoad: Observable<void>;
         readonly storageStatus: Observable<StorageStatus>;
@@ -1047,7 +1159,8 @@ declare type Room<TPresence extends JsonObject, TStorage extends LsonObject, TUs
      */
     getStorageStatus(): StorageStatus;
     /**
-     * Close room connection and try to reconnect
+     * Reconnect the room to the Liveblocks server by re-establishing a fresh
+     * connection. If the room is not connected yet, initiate it.
      */
     reconnect(): void;
 };
@@ -1114,14 +1227,17 @@ declare type AuthEndpoint = string | ((room: string) => Promise<{
  */
 declare type ClientOptions = {
     throttle?: number;
+    lostConnectionTimeout?: number;
     polyfills?: Polyfills;
     unstable_fallbackToHTTP?: boolean;
     /**
-     * Backward-compatible way to set `polyfills.fetch`.
+     * @deprecated Use `polyfills: { fetch: ... }` instead.
+     * This option will be removed in a future release.
      */
     fetchPolyfill?: Polyfills["fetch"];
     /**
-     * Backward-compatible way to set `polyfills.WebSocket`.
+     * @deprecated Use `polyfills: { WebSocket: ... }` instead.
+     * This option will be removed in a future release.
      */
     WebSocketPolyfill?: Polyfills["WebSocket"];
 } & ({
@@ -1253,6 +1369,12 @@ declare function tryParseJson(rawMessage: string): Json | undefined;
  * Decode base64 string.
  */
 declare function b64decode(b64value: string): string;
+/**
+ * Returns whatever the given promise returns, but will be rejected with
+ * a "Timed out" error if the given promise does not return or reject within
+ * the given timeout period (in milliseconds).
+ */
+declare function withTimeout<T>(promise: Promise<T>, millis: number, errmsg?: string): Promise<T>;
 
 /**
  * Positions, aka the Pos type, are efficient encodings of "positions" in
@@ -1330,31 +1452,6 @@ declare function asPos(str: string): Pos;
  */
 declare function shallow(a: unknown, b: unknown): boolean;
 
-declare type AppOnlyAuthToken = {
-    appId: string;
-    roomId?: never;
-    scopes: string[];
-};
-declare type RoomAuthToken = {
-    appId: string;
-    roomId: string;
-    scopes: string[];
-    actor: number;
-    maxConnectionsPerRoom?: number;
-    info?: Json;
-    groupIds?: string[];
-} & ({
-    id: string;
-    anonymousId?: never;
-} | {
-    id?: never;
-    anonymousId: string;
-});
-declare type AuthToken = AppOnlyAuthToken | RoomAuthToken;
-declare function isAppOnlyAuthToken(data: JsonObject): data is AppOnlyAuthToken;
-declare function isRoomAuthToken(data: JsonObject): data is RoomAuthToken;
-declare function isAuthToken(data: JsonObject): data is AuthToken;
-
 declare enum ClientMsgCode {
     UPDATE_PRESENCE = 100,
     BROADCAST_EVENT = 103,
@@ -1725,7 +1822,7 @@ declare type ClientToPanelMessage =
  | {
     msg: "room::sync::full";
     roomId: string;
-    status: ConnectionStatus;
+    status: Status;
     storage: readonly LsonTreeNode[] | null;
     me: UserTreeNode | null;
     others: readonly UserTreeNode[];
@@ -1736,7 +1833,7 @@ declare type ClientToPanelMessage =
  | {
     msg: "room::sync::partial";
     roomId: string;
-    status?: ConnectionStatus;
+    status?: Status;
     storage?: readonly LsonTreeNode[];
     me?: UserTreeNode;
     others?: readonly UserTreeNode[];
@@ -1787,4 +1884,4 @@ declare type EnsureJson<T> = [
     [K in keyof T]: EnsureJson<T[K]>;
 };
 
-export { AckOp, AppOnlyAuthToken, AuthToken, BaseUserMeta, BroadcastEventClientMsg, BroadcastOptions, BroadcastedEventServerMsg, Client, ClientMsg, ClientMsgCode, ConnectionStatus, CrdtType, CreateChildOp, CreateListOp, CreateMapOp, CreateObjectOp, CreateOp, CreateRegisterOp, CreateRootObjectOp, DeleteCrdtOp, DeleteObjectKeyOp, DevToolsTreeNode as DevTools, protocol as DevToolsMsg, EnsureJson, FetchStorageClientMsg, History, IWebSocket, IWebSocketCloseEvent, IWebSocketEvent, IWebSocketInstance, IWebSocketMessageEvent, IdTuple, Immutable, InitialDocumentStateServerMsg, Json, JsonArray, JsonObject, JsonScalar, LiveList, LiveListUpdate, LiveMap, LiveMapUpdate, LiveNode, LiveObject, LiveObjectUpdate, LiveStructure, Lson, LsonObject, NodeMap, Op, OpCode, Others, ParentToChildNodeMap, PlainLson, PlainLsonFields, PlainLsonList, PlainLsonMap, PlainLsonObject, RejectedStorageOpServerMsg, Resolve, Room, RoomAuthToken, RoomInitializers, RoomStateServerMsg, SerializedChild, SerializedCrdt, SerializedList, SerializedMap, SerializedObject, SerializedRegister, SerializedRootObject, ServerMsg, ServerMsgCode, SetParentKeyOp, StorageStatus, StorageUpdate, ToImmutable, ToJson, UpdateObjectOp, UpdatePresenceClientMsg, UpdatePresenceServerMsg, UpdateStorageClientMsg, UpdateStorageServerMsg, User, UserJoinServerMsg, UserLeftServerMsg, WebsocketCloseCodes, asArrayWithLegacyMethods, asPos, assert, assertNever, b64decode, createClient, deprecate, deprecateIf, errorIf, freeze, isAppOnlyAuthToken, isAuthToken, isChildCrdt, isJsonArray, isJsonObject, isJsonScalar, isPlainObject, isRoomAuthToken, isRootCrdt, legacy_patchImmutableObject, lsonToJson, makePosition, nn, patchLiveObjectKey, shallow, throwUsageError, toPlainLson, tryParseJson };
+export { AckOp, AppOnlyAuthToken, AuthToken, BaseAuthResult, BaseUserMeta, BroadcastEventClientMsg, BroadcastOptions, BroadcastedEventServerMsg, Client, ClientMsg, ClientMsgCode, CrdtType, CreateChildOp, CreateListOp, CreateMapOp, CreateObjectOp, CreateOp, CreateRegisterOp, CreateRootObjectOp, Delegates, DeleteCrdtOp, DeleteObjectKeyOp, DevToolsTreeNode as DevTools, protocol as DevToolsMsg, EnsureJson, FetchStorageClientMsg, History, IWebSocket, IWebSocketCloseEvent, IWebSocketEvent, IWebSocketInstance, IWebSocketMessageEvent, IdTuple, Immutable, InitialDocumentStateServerMsg, Json, JsonArray, JsonObject, JsonScalar, LegacyConnectionStatus, LiveList, LiveListUpdate, LiveMap, LiveMapUpdate, LiveNode, LiveObject, LiveObjectUpdate, LiveStructure, LostConnectionEvent, Lson, LsonObject, NodeMap, Op, OpCode, Others, ParentToChildNodeMap, PlainLson, PlainLsonFields, PlainLsonList, PlainLsonMap, PlainLsonObject, RejectedStorageOpServerMsg, Resolve, Room, RoomAuthToken, RoomInitializers, RoomStateServerMsg, SerializedChild, SerializedCrdt, SerializedList, SerializedMap, SerializedObject, SerializedRegister, SerializedRootObject, ServerMsg, ServerMsgCode, SetParentKeyOp, Status, StorageStatus, StorageUpdate, ToImmutable, ToJson, UpdateObjectOp, UpdatePresenceClientMsg, UpdatePresenceServerMsg, UpdateStorageClientMsg, UpdateStorageServerMsg, User, UserJoinServerMsg, UserLeftServerMsg, WebsocketCloseCodes, asArrayWithLegacyMethods, asPos, assert, assertNever, b64decode, createClient, deprecate, deprecateIf, errorIf, freeze, isAppOnlyAuthToken, isAuthToken, isChildCrdt, isJsonArray, isJsonObject, isJsonScalar, isPlainObject, isRoomAuthToken, isRootCrdt, legacy_patchImmutableObject, lsonToJson, makePosition, nn, patchLiveObjectKey, shallow, throwUsageError, toPlainLson, tryParseJson, withTimeout };