@liveblocks/client 0.15.0-alpha.3 → 0.15.1

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

@@ -1,41 +1,189 @@
-import { AbstractCrdt } from "./AbstractCrdt";
-import type { LiveList } from "./LiveList";
-import type { LiveMap } from "./LiveMap";
-import type { LiveObject } from "./LiveObject";
-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, }: {
+/**
+ * The LiveList class represents an ordered collection of items that is synchorinized across clients.
+ */
+declare class LiveList<T> extends AbstractCrdt {
+    #private;
+    constructor(items?: T[]);
+    /**
+     * Returns the number of elements.
+     */
+    get length(): number;
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * Move one element from one index to another.
+     * @param index The index of the element to move
+     * @param targetIndex The index where the element should be after moving.
+     */
+    move(index: number, targetIndex: number): void;
+    /**
+     * Deletes an element at the specified index
+     * @param index The index of the element to delete
+     */
+    delete(index: number): void;
+    clear(): void;
+    /**
+     * Returns an Array of all the elements in the LiveList.
+     */
+    toArray(): T[];
+    /**
+     * 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;
+    /**
+     * 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[];
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * Executes a provided function once for each element.
+     * @param callbackfn Function to execute on each element.
+     */
+    forEach(callbackfn: (value: T, 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;
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * 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[];
+    /**
+     * 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;
+    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;
+}
+
+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;
 }) => void;
-export declare type ErrorCallback = (error: Error) => void;
-export declare type ConnectionCallback = (state: ConnectionState) => void;
-export declare type RoomEventCallbackMap = {
-    "my-presence": MyPresenceCallback;
-    others: OthersEventCallback;
-    event: EventCallback;
-    error: ErrorCallback;
-    connection: ConnectionCallback;
-};
-export declare type UpdateDelta = {
+declare type ErrorCallback = (error: Error) => void;
+declare type ConnectionCallback = (state: ConnectionState) => void;
+declare type UpdateDelta = {
     type: "update";
 } | {
     type: "delete";
 };
-export declare type LiveMapUpdates<TKey extends string = string, TValue = any> = {
+declare type LiveMapUpdates<TKey extends string = string, TValue = any> = {
     type: "LiveMap";
     node: LiveMap<TKey, TValue>;
     updates: Record<TKey, UpdateDelta>;
 };
-export declare type LiveObjectUpdateDelta<T> = Partial<{
+declare type LiveObjectUpdateDelta<T> = Partial<{
     [Property in keyof T]: UpdateDelta;
 }>;
-export declare type LiveObjectUpdates<TData = any> = {
+declare type LiveObjectUpdates<TData = any> = {
     type: "LiveObject";
     node: LiveObject<TData>;
     updates: LiveObjectUpdateDelta<TData>;
 };
-export declare type LiveListUpdateDelta = {
+declare type LiveListUpdateDelta = {
     index: number;
     item: AbstractCrdt;
     type: "insert";
@@ -48,12 +196,12 @@ export declare type LiveListUpdateDelta = {
     item: AbstractCrdt;
     type: "move";
 };
-export declare type LiveListUpdates<TItem = any> = {
+declare type LiveListUpdates<TItem = any> = {
     type: "LiveList";
     node: LiveList<TItem>;
     updates: LiveListUpdateDelta[];
 };
-export declare type BroadcastOptions = {
+declare type BroadcastOptions = {
     /**
      * Whether or not event is queued if the connection is currently closed.
      *
@@ -61,9 +209,8 @@ export declare type BroadcastOptions = {
      */
     shouldQueueEventIfNotReady: boolean;
 };
-export declare type StorageUpdate = LiveMapUpdates | LiveObjectUpdates | LiveListUpdates;
-export declare type StorageCallback = (updates: StorageUpdate[]) => void;
-export declare type Client = {
+declare type StorageUpdate = LiveMapUpdates | LiveObjectUpdates | LiveListUpdates;
+declare type Client = {
     /**
      * Gets a room. Returns null if {@link Client.enter} has not been called previously.
      *
@@ -85,15 +232,10 @@ export declare type Client = {
      */
     leave(roomId: string): void;
 };
-export declare type AuthenticationToken = {
-    actor: number;
-    id?: string;
-    info?: any;
-};
 /**
  * Represents all the other users connected in the room. Treated as immutable.
  */
-export interface Others<TPresence extends Presence = Presence> {
+interface Others<TPresence extends Presence = Presence> {
     /**
      * Number of other users in the room.
      */
@@ -114,7 +256,7 @@ export interface Others<TPresence extends Presence = Presence> {
 /**
  * Represents a user connected in a room. Treated as immutable.
  */
-export declare type User<TPresence extends Presence = Presence> = {
+declare type User<TPresence extends Presence = Presence> = {
     /**
      * The connection id of the user. It is unique and increment at every new connection.
      */
@@ -133,18 +275,18 @@ export declare type User<TPresence extends Presence = Presence> = {
      */
     readonly presence?: TPresence;
 };
-export declare type Presence = {
+declare type Presence = {
     [key: string]: any;
 };
 declare type AuthEndpointCallback = (room: string) => Promise<{
     token: string;
 }>;
-export declare type AuthEndpoint = string | AuthEndpointCallback;
+declare type AuthEndpoint = string | AuthEndpointCallback;
 /**
  * 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.
  */
-export declare type ClientOptions = {
+declare type ClientOptions = {
     throttle?: number;
     fetchPolyfill?: any;
     WebSocketPolyfill?: any;
@@ -155,30 +297,8 @@ export declare type ClientOptions = {
     publicApiKey?: never;
     authEndpoint: AuthEndpoint;
 });
-export declare type AuthorizeResponse = {
-    token: string;
-};
-export declare type Authentication = {
-    type: "public";
-    publicApiKey: string;
-    url: string;
-} | {
-    type: "private";
-    url: string;
-} | {
-    type: "custom";
-    callback: (room: string) => Promise<AuthorizeResponse>;
-};
 declare type ConnectionState = "closed" | "authenticating" | "unavailable" | "failed" | "open" | "connecting";
-export declare type Connection = {
-    state: "closed" | "authenticating" | "unavailable" | "failed";
-} | {
-    state: "open" | "connecting";
-    id: number;
-    userId?: string;
-    userInfo?: any;
-};
-export declare type OthersEvent<T extends Presence = Presence> = {
+declare type OthersEvent<T extends Presence = Presence> = {
     type: "leave";
     user: User<T>;
 } | {
@@ -191,7 +311,11 @@ export declare type OthersEvent<T extends Presence = Presence> = {
 } | {
     type: "reset";
 };
-export declare type Room = {
+declare type Room = {
+    /**
+     * The id of the room.
+     */
+    readonly id: string;
     getConnectionState(): ConnectionState;
     subscribe: {
         /**
@@ -499,4 +623,72 @@ export declare type Room = {
      */
     batch: (fn: () => void) => void;
 };
-export {};
+
+declare abstract class AbstractCrdt {
+    #private;
+    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<T extends Record<string, any> = Record<string, any>> extends AbstractCrdt {
+    #private;
+    constructor(object?: T);
+    /**
+     * Transform the LiveObject into a javascript object
+     */
+    toObject(): T;
+    /**
+     * 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;
+    /**
+     * 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];
+    /**
+     * Deletes a key from the LiveObject
+     * @param key The key of the property to delete
+     */
+    delete(key: keyof T): void;
+    /**
+     * Adds or updates multiple properties at once with an object.
+     * @param overrides The object used to overrides properties
+     */
+    update(overrides: Partial<T>): void;
+}
+
+/**
+ * Create a client that will be responsible to communicate with liveblocks servers.
+ *
+ * @example
+ * const client = createClient({
+ *   authEndpoint: "/api/auth"
+ * });
+ *
+ * // It's also possible to use a function to call your authentication endpoint.
+ * // Useful to add additional headers or use an API wrapper (like Firebase functions)
+ * const client = createClient({
+ *   authEndpoint: async (room) => {
+ *     const response = await fetch("/api/auth", {
+ *       method: "POST",
+ *       headers: {
+ *          Authentication: "token",
+ *          "Content-Type": "application/json"
+ *       },
+ *       body: JSON.stringify({ room })
+ *     });
+ *
+ *     return await response.json();
+ *   }
+ * });
+ */
+declare function createClient(options: ClientOptions): Client;
+
+export { BroadcastOptions, Client, LiveList, LiveMap, LiveObject, Others, Presence, Room, StorageUpdate, User, createClient };