@liveblocks/client - npm Package Compare versions

Comparing version 0.8.0 to 0.8.1

lib/cjs/client.d.ts

 import { ClientOptions, Client } from "./types";
+/**
+ * Create a client that will be responsible to communicate with liveblocks servers.
+ *
+ * ### Example
+ * ```
+ * const client = createClient({
+ *   authEndpoint: "/api/auth"
+ * })
+ * ```
+ */
 export declare function createClient(options: ClientOptions): Client;

lib/cjs/client.js

@@ -5,2 +5,12 @@ "use strict";
 const room_1 = require("./room");
+/**
+ * Create a client that will be responsible to communicate with liveblocks servers.
+ *
+ * ### Example
+ * ```
+ * const client = createClient({
+ *   authEndpoint: "/api/auth"
+ * })
+ * ```
+ */
 function createClient(options) {
@@ -14,13 +24,14 @@ if (typeof options.throttle === "number") {
     function getRoom(roomId) {
-        return rooms.get(roomId) || null;
+        const internalRoom = rooms.get(roomId);
+        return internalRoom ? internalRoom.room : null;
     }
     function enter(roomId, initialPresence) {
-        let room = rooms.get(roomId);
-        if (room) {
-            return room;
+        let internalRoom = rooms.get(roomId);
+        if (internalRoom) {
+            return internalRoom.room;
         }
-        room = room_1.createRoom(roomId, Object.assign(Object.assign({}, options), { initialPresence }));
-        rooms.set(roomId, room);
-        room.connect();
-        return room;
+        internalRoom = room_1.createRoom(roomId, Object.assign(Object.assign({}, options), { initialPresence }));
+        rooms.set(roomId, internalRoom);
+        internalRoom.connect();
+        return internalRoom.room;
     }
@@ -38,3 +49,3 @@ function leave(roomId) {
             for (const [, room] of rooms) {
-                room._onNavigatorOnline();
+                room.onNavigatorOnline();
             }
@@ -46,3 +57,3 @@ });
             for (const [, room] of rooms) {
-                room._onVisibilityChange(document.visibilityState);
+                room.onVisibilityChange(document.visibilityState);
             }
@@ -49,0 +60,0 @@ });

lib/cjs/room.d.ts

@@ -105,5 +105,12 @@ import { RecordData, List } from ".";
 export declare function defaultState(me?: Presence): State;
+export declare type InternalRoom = {
+    room: Room;
+    connect: () => void;
+    disconnect: () => void;
+    onNavigatorOnline: () => void;
+    onVisibilityChange: (visibilityState: VisibilityState) => void;
+};
 export declare function createRoom(name: string, options: ClientOptions & {
     initialPresence?: Presence;
-}): Room;
+}): InternalRoom;
 export {};

lib/cjs/room.js

@@ -655,4 +655,2 @@ "use strict";
         /////////////
-        connect: machine.connect,
-        disconnect: machine.disconnect,
         getConnectionState: machine.selectors.getConnectionState,
@@ -682,5 +680,9 @@ getCurrentUser: machine.selectors.getCurrentUser,
     };
-    room._onNavigatorOnline = machine.onNavigatorOnline;
-    room._onVisibilityChange = machine.onVisibilityChange;
-    return room;
+    return {
+        connect: machine.connect,
+        disconnect: machine.disconnect,
+        onNavigatorOnline: machine.onNavigatorOnline,
+        onVisibilityChange: machine.onVisibilityChange,
+        room,
+    };
 }
@@ -687,0 +689,0 @@ exports.createRoom = createRoom;

lib/cjs/types.d.ts

 import { RecordData, Record, List } from "./doc";
+export declare type StorageCallback<T extends RecordData = RecordData> = (storage: LiveStorage<T>) => void;
+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, }: {
+    connectionId: number;
+    event: any;
+}) => void;
+export declare type ErrorCallback = (error: Error) => void;
+export declare type ConnectionCallback = (state: ConnectionState) => void;
+export declare type RoomEventCallbackMap = {
+    storage: StorageCallback;
+    "my-presence": MyPresenceCallback;
+    others: OthersEventCallback;
+    event: EventCallback;
+    error: ErrorCallback;
+    connection: ConnectionCallback;
+};
+export declare type CreateRecord = Room["createRecord"];
+export declare type CreateList = Room["createList"];
+export declare type InitialStorageFactory<TRoot = RecordData> = (factories: {
+    createRecord: CreateRecord;
+    createList: CreateList;
+}) => TRoot;
+export declare type Client = {
+    /**
+     * Get a room. Returns null if you never entered the room
+     * @param roomId - The id of the room
+     */
+    getRoom(roomId: string): Room | null;
+    /**
+     * Enter a room.
+     * @param roomId - The id of the room
+     * @param defaultPresence - Optional. Should be serializable to JSON. If omitted, an empty object will be used.
+     */
+    enter(roomId: string, defaultPresence?: Presence): Room;
+    /**
+     * Leave a room.
+     * @param roomId - The id of the room
+     */
+    leave(roomId: string): void;
+};
+export declare type AuthenticationToken = {
+    actor: number;
+    id?: string;
+    info?: any;
+};
 /**
@@ -51,3 +97,3 @@ * Represents all the other users connected in the room. Treated as immutable.
      * 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 attach additional headers.
+     * Can be an url or a callback if you need to add additional headers.
      */
@@ -94,25 +140,107 @@ authEndpoint: AuthEndpoint;
 export declare type Room = {
-    connect(): void;
-    disconnect(): void;
     getConnectionState(): ConnectionState;
-    getCurrentUser<TPresence extends Presence = Presence>(): User<TPresence> | null;
     subscribe: {
+        /**
+         * Subscribe to the current user presence updates.
+         */
         <T extends Presence>(type: "my-presence", listener: MyPresenceCallback<T>): void;
+        /**
+         * Subscribe to the other users updates.
+         * The listener will be called when a user enters or leaves the room or when a user update its presence.
+         */
         <T extends Presence>(type: "others", listener: OthersEventCallback<T>): void;
+        /**
+         * Subscribe to events broadcasted by room.broadcastEvent
+         */
         (type: "event", listener: EventCallback): void;
         <T extends RecordData>(type: "storage", listener: StorageCallback<T>): void;
+        /**
+         * Subscribe to errors thrown in the room.
+         */
         (type: "error", listener: ErrorCallback): void;
+        /**
+         * Subscribe to connection state updates.
+         */
         (type: "connection", listener: ConnectionCallback): void;
     };
     unsubscribe: {
+        /**
+         * Unsubscribe to the current user presence updates.
+         */
         <T extends Presence>(type: "my-presence", listener: MyPresenceCallback<T>): void;
+        /**
+         * Unsubscribe to the other users updates.
+         */
         <T extends Presence>(type: "others", listener: OthersEventCallback<T>): void;
+        /**
+         * Unsubscribe to events broadcasted by room.broadcastEvent
+         */
         (type: "event", listener: EventCallback): void;
         <T extends RecordData>(type: "storage", listener: StorageCallback<T>): void;
+        /**
+         * Unsubscribe to errors thrown in the room.
+         */
         (type: "error", listener: ErrorCallback): void;
+        /**
+         * Unsubscribe to connection state updates.
+         */
         (type: "connection", listener: ConnectionCallback): void;
     };
+    /**
+     * Get the current user.
+     *
+     * ### Example
+     * ``` typescript
+     * const user = room.getCurrentUser();
+     * ```
+     */
+    getCurrentUser<TPresence extends Presence = Presence>(): User<TPresence> | null;
+    /**
+     * Get the presence of the current user.
+     *
+     * ### Example
+     * ``` typescript
+     * const presence = room.getPresence();
+     * ```
+     */
     getPresence: <T extends Presence>() => T;
+    /**
+     * Get all the other users in the room.
+     *
+     * ### Example
+     * ``` typescript
+     * const others = room.getOthers();
+     * ```
+     */
     getOthers: <T extends Presence>() => Others<T>;
+    /**
+     * Update 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.
+     *
+     * ### Example
+     * ``` typescript
+     * room.updatePresence({ x: 0 });
+     * room.updatePresence({ y: 0 });
+     *
+     * const presence = room.getPresence();
+     * // presence is equivalent to { x: 0, y: 0 }
+     * ```
+     */
     updatePresence: <T extends Presence>(overrides: Partial<T>) => void;
+    /**
+     * Broadcast an event to other users in the room.
+     * @param {any} event - the event to broadcast. Should be serializable to JSON
+     *
+     * ### Example
+     * ``` typescript
+     *
+     * // On client A
+     * room.broadcastEvent({ type: "EMOJI", emoji: 🔥 });
+     *
+     * // On client B
+     * room.subscribe("event", ({ event }) => {
+     *
+     * });
+     * ```
+     */
     broadcastEvent: (event: any) => void;
@@ -129,35 +257,2 @@ getStorage: () => LiveStorage;
 };
-export declare type StorageCallback<T extends RecordData = RecordData> = (storage: LiveStorage<T>) => void;
-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, }: {
-    connectionId: number;
-    event: any;
-}) => void;
-export declare type ErrorCallback = (error: Error) => void;
-export declare type ConnectionCallback = (state: ConnectionState) => void;
-export declare type RoomEventCallbackMap = {
-    storage: StorageCallback;
-    "my-presence": MyPresenceCallback;
-    others: OthersEventCallback;
-    event: EventCallback;
-    error: ErrorCallback;
-    connection: ConnectionCallback;
-};
-export declare type CreateRecord = Room["createRecord"];
-export declare type CreateList = Room["createList"];
-export declare type InitialStorageFactory<TRoot = RecordData> = (factories: {
-    createRecord: CreateRecord;
-    createList: CreateList;
-}) => TRoot;
-export declare type Client = {
-    getRoom(roomId: string): Room | null;
-    enter(roomId: string, defaultPresence?: Presence): Room;
-    leave(roomId: string): void;
-};
-export declare type AuthenticationToken = {
-    actor: number;
-    id?: string;
-    info?: any;
-};
 export {};

lib/esm/client.d.ts

 import { ClientOptions, Client } from "./types";
+/**
+ * Create a client that will be responsible to communicate with liveblocks servers.
+ *
+ * ### Example
+ * ```
+ * const client = createClient({
+ *   authEndpoint: "/api/auth"
+ * })
+ * ```
+ */
 export declare function createClient(options: ClientOptions): Client;

lib/esm/client.js

 import { createRoom } from "./room";
+/**
+ * Create a client that will be responsible to communicate with liveblocks servers.
+ *
+ * ### Example
+ * ```
+ * const client = createClient({
+ *   authEndpoint: "/api/auth"
+ * })
+ * ```
+ */
 export function createClient(options) {
@@ -10,13 +20,14 @@ if (typeof options.throttle === "number") {
     function getRoom(roomId) {
-        return rooms.get(roomId) || null;
+        const internalRoom = rooms.get(roomId);
+        return internalRoom ? internalRoom.room : null;
     }
     function enter(roomId, initialPresence) {
-        let room = rooms.get(roomId);
-        if (room) {
-            return room;
+        let internalRoom = rooms.get(roomId);
+        if (internalRoom) {
+            return internalRoom.room;
         }
-        room = createRoom(roomId, Object.assign(Object.assign({}, options), { initialPresence }));
-        rooms.set(roomId, room);
-        room.connect();
-        return room;
+        internalRoom = createRoom(roomId, Object.assign(Object.assign({}, options), { initialPresence }));
+        rooms.set(roomId, internalRoom);
+        internalRoom.connect();
+        return internalRoom.room;
     }
@@ -34,3 +45,3 @@ function leave(roomId) {
             for (const [, room] of rooms) {
-                room._onNavigatorOnline();
+                room.onNavigatorOnline();
             }
@@ -42,3 +53,3 @@ });
             for (const [, room] of rooms) {
-                room._onVisibilityChange(document.visibilityState);
+                room.onVisibilityChange(document.visibilityState);
             }
@@ -45,0 +56,0 @@ });

lib/esm/room.d.ts

@@ -105,5 +105,12 @@ import { RecordData, List } from ".";
 export declare function defaultState(me?: Presence): State;
+export declare type InternalRoom = {
+    room: Room;
+    connect: () => void;
+    disconnect: () => void;
+    onNavigatorOnline: () => void;
+    onVisibilityChange: (visibilityState: VisibilityState) => void;
+};
 export declare function createRoom(name: string, options: ClientOptions & {
     initialPresence?: Presence;
-}): Room;
+}): InternalRoom;
 export {};

lib/esm/room.js

@@ -631,4 +631,2 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
         /////////////
-        connect: machine.connect,
-        disconnect: machine.disconnect,
         getConnectionState: machine.selectors.getConnectionState,
@@ -658,5 +656,9 @@ getCurrentUser: machine.selectors.getCurrentUser,
     };
-    room._onNavigatorOnline = machine.onNavigatorOnline;
-    room._onVisibilityChange = machine.onVisibilityChange;
-    return room;
+    return {
+        connect: machine.connect,
+        disconnect: machine.disconnect,
+        onNavigatorOnline: machine.onNavigatorOnline,
+        onVisibilityChange: machine.onVisibilityChange,
+        room,
+    };
 }
@@ -663,0 +665,0 @@ class LiveblocksError extends Error {

lib/esm/types.d.ts

 import { RecordData, Record, List } from "./doc";
+export declare type StorageCallback<T extends RecordData = RecordData> = (storage: LiveStorage<T>) => void;
+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, }: {
+    connectionId: number;
+    event: any;
+}) => void;
+export declare type ErrorCallback = (error: Error) => void;
+export declare type ConnectionCallback = (state: ConnectionState) => void;
+export declare type RoomEventCallbackMap = {
+    storage: StorageCallback;
+    "my-presence": MyPresenceCallback;
+    others: OthersEventCallback;
+    event: EventCallback;
+    error: ErrorCallback;
+    connection: ConnectionCallback;
+};
+export declare type CreateRecord = Room["createRecord"];
+export declare type CreateList = Room["createList"];
+export declare type InitialStorageFactory<TRoot = RecordData> = (factories: {
+    createRecord: CreateRecord;
+    createList: CreateList;
+}) => TRoot;
+export declare type Client = {
+    /**
+     * Get a room. Returns null if you never entered the room
+     * @param roomId - The id of the room
+     */
+    getRoom(roomId: string): Room | null;
+    /**
+     * Enter a room.
+     * @param roomId - The id of the room
+     * @param defaultPresence - Optional. Should be serializable to JSON. If omitted, an empty object will be used.
+     */
+    enter(roomId: string, defaultPresence?: Presence): Room;
+    /**
+     * Leave a room.
+     * @param roomId - The id of the room
+     */
+    leave(roomId: string): void;
+};
+export declare type AuthenticationToken = {
+    actor: number;
+    id?: string;
+    info?: any;
+};
 /**
@@ -51,3 +97,3 @@ * Represents all the other users connected in the room. Treated as immutable.
      * 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 attach additional headers.
+     * Can be an url or a callback if you need to add additional headers.
      */
@@ -94,25 +140,107 @@ authEndpoint: AuthEndpoint;
 export declare type Room = {
-    connect(): void;
-    disconnect(): void;
     getConnectionState(): ConnectionState;
-    getCurrentUser<TPresence extends Presence = Presence>(): User<TPresence> | null;
     subscribe: {
+        /**
+         * Subscribe to the current user presence updates.
+         */
         <T extends Presence>(type: "my-presence", listener: MyPresenceCallback<T>): void;
+        /**
+         * Subscribe to the other users updates.
+         * The listener will be called when a user enters or leaves the room or when a user update its presence.
+         */
         <T extends Presence>(type: "others", listener: OthersEventCallback<T>): void;
+        /**
+         * Subscribe to events broadcasted by room.broadcastEvent
+         */
         (type: "event", listener: EventCallback): void;
         <T extends RecordData>(type: "storage", listener: StorageCallback<T>): void;
+        /**
+         * Subscribe to errors thrown in the room.
+         */
         (type: "error", listener: ErrorCallback): void;
+        /**
+         * Subscribe to connection state updates.
+         */
         (type: "connection", listener: ConnectionCallback): void;
     };
     unsubscribe: {
+        /**
+         * Unsubscribe to the current user presence updates.
+         */
         <T extends Presence>(type: "my-presence", listener: MyPresenceCallback<T>): void;
+        /**
+         * Unsubscribe to the other users updates.
+         */
         <T extends Presence>(type: "others", listener: OthersEventCallback<T>): void;
+        /**
+         * Unsubscribe to events broadcasted by room.broadcastEvent
+         */
         (type: "event", listener: EventCallback): void;
         <T extends RecordData>(type: "storage", listener: StorageCallback<T>): void;
+        /**
+         * Unsubscribe to errors thrown in the room.
+         */
         (type: "error", listener: ErrorCallback): void;
+        /**
+         * Unsubscribe to connection state updates.
+         */
         (type: "connection", listener: ConnectionCallback): void;
     };
+    /**
+     * Get the current user.
+     *
+     * ### Example
+     * ``` typescript
+     * const user = room.getCurrentUser();
+     * ```
+     */
+    getCurrentUser<TPresence extends Presence = Presence>(): User<TPresence> | null;
+    /**
+     * Get the presence of the current user.
+     *
+     * ### Example
+     * ``` typescript
+     * const presence = room.getPresence();
+     * ```
+     */
     getPresence: <T extends Presence>() => T;
+    /**
+     * Get all the other users in the room.
+     *
+     * ### Example
+     * ``` typescript
+     * const others = room.getOthers();
+     * ```
+     */
     getOthers: <T extends Presence>() => Others<T>;
+    /**
+     * Update 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.
+     *
+     * ### Example
+     * ``` typescript
+     * room.updatePresence({ x: 0 });
+     * room.updatePresence({ y: 0 });
+     *
+     * const presence = room.getPresence();
+     * // presence is equivalent to { x: 0, y: 0 }
+     * ```
+     */
     updatePresence: <T extends Presence>(overrides: Partial<T>) => void;
+    /**
+     * Broadcast an event to other users in the room.
+     * @param {any} event - the event to broadcast. Should be serializable to JSON
+     *
+     * ### Example
+     * ``` typescript
+     *
+     * // On client A
+     * room.broadcastEvent({ type: "EMOJI", emoji: 🔥 });
+     *
+     * // On client B
+     * room.subscribe("event", ({ event }) => {
+     *
+     * });
+     * ```
+     */
     broadcastEvent: (event: any) => void;
@@ -129,35 +257,2 @@ getStorage: () => LiveStorage;
 };
-export declare type StorageCallback<T extends RecordData = RecordData> = (storage: LiveStorage<T>) => void;
-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, }: {
-    connectionId: number;
-    event: any;
-}) => void;
-export declare type ErrorCallback = (error: Error) => void;
-export declare type ConnectionCallback = (state: ConnectionState) => void;
-export declare type RoomEventCallbackMap = {
-    storage: StorageCallback;
-    "my-presence": MyPresenceCallback;
-    others: OthersEventCallback;
-    event: EventCallback;
-    error: ErrorCallback;
-    connection: ConnectionCallback;
-};
-export declare type CreateRecord = Room["createRecord"];
-export declare type CreateList = Room["createList"];
-export declare type InitialStorageFactory<TRoot = RecordData> = (factories: {
-    createRecord: CreateRecord;
-    createList: CreateList;
-}) => TRoot;
-export declare type Client = {
-    getRoom(roomId: string): Room | null;
-    enter(roomId: string, defaultPresence?: Presence): Room;
-    leave(roomId: string): void;
-};
-export declare type AuthenticationToken = {
-    actor: number;
-    id?: string;
-    info?: any;
-};
 export {};

package.json

 {
   "name": "@liveblocks/client",
-  "version": "0.8.0",
+  "version": "0.8.1",
   "description": "",
@@ -10,2 +10,11 @@ "main": "./lib/cjs/index.js",
   ],
+  "keywords": [
+    "liveblocks",
+    "multiplayer",
+    "live-cursors",
+    "collaborative"
+  ],
+  "bugs": {
+    "url": "https://github.com/liveblocks/liveblocks/issues"
+  },
   "scripts": {
@@ -27,3 +36,8 @@ "build-and-pack": "npm run build && npm pack",
     "typescript": "^4.1.5"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/liveblocks/liveblocks.git",
+    "directory": "packages/liveblocks"
   }
 }

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

No README

Quality

Package does not have a README. This may indicate a failed publish or a low quality package.

Found 1 instance in 1 package

No bug tracker

Maintenance

Package does not have a linked bug tracker in package.json.

Found 1 instance in 1 package

No repository

Supply chain risk

Package does not have a linked source code repository. Without this field, a package will have no reference to the location of the source code use to generate the package.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

217302

increased by3.86%

Number of package files

39

increased by2.63%

Lines of code

4063

increased by6.56%

Number of low maintenance alerts

1

decreased by-50%

Number of medium quality alerts

0

decreased by-100%

Number of lines in readme file

28

increased byInfinity%

Number of low supply chain risk alerts

0

decreased by-100%

No dependency changes