@liveblocks/client 0.16.15 → 0.17.0-beta1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (10) hide show
  1. package/index.d.ts +28 -8
  2. package/index.js +1290 -830
  3. package/index.mjs +1091 -782
  4. package/internal.d.ts +418 -248
  5. package/internal.js +313 -168
  6. package/internal.mjs +264 -130
  7. package/package.json +15 -10
  8. package/shared.d.ts +719 -650
  9. package/shared.js +2571 -1331
  10. package/shared.mjs +1992 -1209
package/shared.d.ts CHANGED
@@ -1,3 +1,208 @@
1
+ declare abstract class AbstractCrdt {
2
+ get roomId(): string | null;
3
+ }
4
+
5
+ /**
6
+ * The LiveList class represents an ordered collection of items that is synchronized across clients.
7
+ */
8
+ declare class LiveList<TItem extends Lson> extends AbstractCrdt {
9
+ constructor(items?: TItem[]);
10
+ /**
11
+ * Returns the number of elements.
12
+ */
13
+ get length(): number;
14
+ /**
15
+ * Adds one element to the end of the LiveList.
16
+ * @param element The element to add to the end of the LiveList.
17
+ */
18
+ push(element: TItem): void;
19
+ /**
20
+ * Inserts one element at a specified index.
21
+ * @param element The element to insert.
22
+ * @param index The index at which you want to insert the element.
23
+ */
24
+ insert(element: TItem, index: number): void;
25
+ /**
26
+ * Move one element from one index to another.
27
+ * @param index The index of the element to move
28
+ * @param targetIndex The index where the element should be after moving.
29
+ */
30
+ move(index: number, targetIndex: number): void;
31
+ /**
32
+ * Deletes an element at the specified index
33
+ * @param index The index of the element to delete
34
+ */
35
+ delete(index: number): void;
36
+ clear(): void;
37
+ set(index: number, item: TItem): void;
38
+ /**
39
+ * Returns an Array of all the elements in the LiveList.
40
+ */
41
+ toArray(): TItem[];
42
+ /**
43
+ * Tests whether all elements pass the test implemented by the provided function.
44
+ * @param predicate Function to test for each element, taking two arguments (the element and its index).
45
+ * @returns true if the predicate function returns a truthy value for every element. Otherwise, false.
46
+ */
47
+ every(predicate: (value: TItem, index: number) => unknown): boolean;
48
+ /**
49
+ * Creates an array with all elements that pass the test implemented by the provided function.
50
+ * @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.
51
+ * @returns An array with the elements that pass the test.
52
+ */
53
+ filter(predicate: (value: TItem, index: number) => unknown): TItem[];
54
+ /**
55
+ * Returns the first element that satisfies the provided testing function.
56
+ * @param predicate Function to execute on each value.
57
+ * @returns The value of the first element in the LiveList that satisfies the provided testing function. Otherwise, undefined is returned.
58
+ */
59
+ find(predicate: (value: TItem, index: number) => unknown): TItem | undefined;
60
+ /**
61
+ * Returns the index of the first element in the LiveList that satisfies the provided testing function.
62
+ * @param predicate Function to execute on each value until the function returns true, indicating that the satisfying element was found.
63
+ * @returns The index of the first element in the LiveList that passes the test. Otherwise, -1.
64
+ */
65
+ findIndex(predicate: (value: TItem, index: number) => unknown): number;
66
+ /**
67
+ * Executes a provided function once for each element.
68
+ * @param callbackfn Function to execute on each element.
69
+ */
70
+ forEach(callbackfn: (value: TItem, index: number) => void): void;
71
+ /**
72
+ * Get the element at the specified index.
73
+ * @param index The index on the element to get.
74
+ * @returns The element at the specified index or undefined.
75
+ */
76
+ get(index: number): TItem | undefined;
77
+ /**
78
+ * Returns the first index at which a given element can be found in the LiveList, or -1 if it is not present.
79
+ * @param searchElement Element to locate.
80
+ * @param fromIndex The index to start the search at.
81
+ * @returns The first index of the element in the LiveList; -1 if not found.
82
+ */
83
+ indexOf(searchElement: TItem, fromIndex?: number): number;
84
+ /**
85
+ * 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.
86
+ * @param searchElement Element to locate.
87
+ * @param fromIndex The index at which to start searching backwards.
88
+ * @returns
89
+ */
90
+ lastIndexOf(searchElement: TItem, fromIndex?: number): number;
91
+ /**
92
+ * Creates an array populated with the results of calling a provided function on every element.
93
+ * @param callback Function that is called for every element.
94
+ * @returns An array with each element being the result of the callback function.
95
+ */
96
+ map<U>(callback: (value: TItem, index: number) => U): U[];
97
+ /**
98
+ * Tests whether at least one element in the LiveList passes the test implemented by the provided function.
99
+ * @param predicate Function to test for each element.
100
+ * @returns true if the callback function returns a truthy value for at least one element. Otherwise, false.
101
+ */
102
+ some(predicate: (value: TItem, index: number) => unknown): boolean;
103
+ [Symbol.iterator](): IterableIterator<TItem>;
104
+ }
105
+
106
+ /**
107
+ * The LiveMap class is similar to a JavaScript Map that is synchronized on all clients.
108
+ * Keys should be a string, and values should be serializable to JSON.
109
+ * If multiple clients update the same property simultaneously, the last modification received by the Liveblocks servers is the winner.
110
+ */
111
+ declare class LiveMap<
112
+ TKey extends string,
113
+ TValue extends Lson
114
+ > extends AbstractCrdt {
115
+ constructor(entries?: readonly (readonly [TKey, TValue])[] | undefined);
116
+ /**
117
+ * @deprecated Please call as `new LiveMap()` or `new LiveMap([])` instead.
118
+ */
119
+ constructor(entries: null);
120
+ /**
121
+ * Returns a specified element from the LiveMap.
122
+ * @param key The key of the element to return.
123
+ * @returns The element associated with the specified key, or undefined if the key can't be found in the LiveMap.
124
+ */
125
+ get(key: TKey): TValue | undefined;
126
+ /**
127
+ * Adds or updates an element with a specified key and a value.
128
+ * @param key The key of the element to add. Should be a string.
129
+ * @param value The value of the element to add. Should be serializable to JSON.
130
+ */
131
+ set(key: TKey, value: TValue): void;
132
+ /**
133
+ * Returns the number of elements in the LiveMap.
134
+ */
135
+ get size(): number;
136
+ /**
137
+ * Returns a boolean indicating whether an element with the specified key exists or not.
138
+ * @param key The key of the element to test for presence.
139
+ */
140
+ has(key: TKey): boolean;
141
+ /**
142
+ * Removes the specified element by key.
143
+ * @param key The key of the element to remove.
144
+ * @returns true if an element existed and has been removed, or false if the element does not exist.
145
+ */
146
+ delete(key: TKey): boolean;
147
+ /**
148
+ * Returns a new Iterator object that contains the [key, value] pairs for each element.
149
+ */
150
+ entries(): IterableIterator<[TKey, TValue]>;
151
+ /**
152
+ * Same function object as the initial value of the entries method.
153
+ */
154
+ [Symbol.iterator](): IterableIterator<[TKey, TValue]>;
155
+ /**
156
+ * Returns a new Iterator object that contains the keys for each element.
157
+ */
158
+ keys(): IterableIterator<TKey>;
159
+ /**
160
+ * Returns a new Iterator object that contains the values for each element.
161
+ */
162
+ values(): IterableIterator<TValue>;
163
+ /**
164
+ * Executes a provided function once per each key/value pair in the Map object, in insertion order.
165
+ * @param callback Function to execute for each entry in the map.
166
+ */
167
+ forEach(
168
+ callback: (value: TValue, key: TKey, map: LiveMap<TKey, TValue>) => void
169
+ ): void;
170
+ }
171
+
172
+ /**
173
+ * The LiveObject class is similar to a JavaScript object that is synchronized on all clients.
174
+ * Keys should be a string, and values should be serializable to JSON.
175
+ * If multiple clients update the same property simultaneously, the last modification received by the Liveblocks servers is the winner.
176
+ */
177
+ declare class LiveObject<O extends LsonObject> extends AbstractCrdt {
178
+ constructor(obj?: O);
179
+ /**
180
+ * Transform the LiveObject into a javascript object
181
+ */
182
+ toObject(): O;
183
+ /**
184
+ * Adds or updates a property with a specified key and a value.
185
+ * @param key The key of the property to add
186
+ * @param value The value of the property to add
187
+ */
188
+ set<TKey extends keyof O>(key: TKey, value: O[TKey]): void;
189
+ /**
190
+ * Returns a specified property from the LiveObject.
191
+ * @param key The key of the property to get
192
+ */
193
+ get<TKey extends keyof O>(key: TKey): O[TKey];
194
+ /**
195
+ * Deletes a key from the LiveObject
196
+ * @param key The key of the property to delete
197
+ */
198
+ delete(key: keyof O): void;
199
+ /**
200
+ * Adds or updates multiple properties at once with an object.
201
+ * @param overrides The object used to overrides properties
202
+ */
203
+ update(overrides: Partial<O>): void;
204
+ }
205
+
1
206
  /**
2
207
  * Represents an indefinitely deep arbitrary JSON data structure. There are
3
208
  * four types that make up the Json family:
@@ -12,189 +217,55 @@ declare type Json = JsonScalar | JsonArray | JsonObject;
12
217
  declare type JsonScalar = string | number | boolean | null;
13
218
  declare type JsonArray = Json[];
14
219
  declare type JsonObject = {
15
- [key: string]: Json | undefined;
220
+ [key: string]: Json | undefined;
16
221
  };
17
222
  declare function isJsonScalar(data: Json): data is JsonScalar;
18
223
  declare function isJsonArray(data: Json): data is JsonArray;
19
224
  declare function isJsonObject(data: Json): data is JsonObject;
20
225
 
226
+ declare type BaseUserMeta = {
227
+ /**
228
+ * The id of the user that has been set in the authentication endpoint.
229
+ * Useful to get additional information about the connected user.
230
+ */
231
+ id?: string;
232
+ /**
233
+ * Additional user information that has been set in the authentication endpoint.
234
+ */
235
+ info?: Json;
236
+ };
237
+
21
238
  /**
22
- * The LiveMap class is similar to a JavaScript Map that is synchronized on all clients.
23
- * Keys should be a string, and values should be serializable to JSON.
24
- * If multiple clients update the same property simultaneously, the last modification received by the Liveblocks servers is the winner.
239
+ * INTERNAL
25
240
  */
26
- declare class LiveMap<TKey extends string = string, TValue extends Lson = Lson> extends AbstractCrdt {
27
- private _map;
28
- constructor(entries?: readonly (readonly [TKey, TValue])[] | undefined);
29
- /**
30
- * @deprecated Please call as `new LiveMap()` or `new LiveMap([])` instead.
31
- */
32
- constructor(entries: null);
33
- /**
34
- * Returns a specified element from the LiveMap.
35
- * @param key The key of the element to return.
36
- * @returns The element associated with the specified key, or undefined if the key can't be found in the LiveMap.
37
- */
38
- get(key: TKey): TValue | undefined;
39
- /**
40
- * Adds or updates an element with a specified key and a value.
41
- * @param key The key of the element to add. Should be a string.
42
- * @param value The value of the element to add. Should be serializable to JSON.
43
- */
44
- set(key: TKey, value: TValue): void;
45
- /**
46
- * Returns the number of elements in the LiveMap.
47
- */
48
- get size(): number;
49
- /**
50
- * Returns a boolean indicating whether an element with the specified key exists or not.
51
- * @param key The key of the element to test for presence.
52
- */
53
- has(key: TKey): boolean;
54
- /**
55
- * Removes the specified element by key.
56
- * @param key The key of the element to remove.
57
- * @returns true if an element existed and has been removed, or false if the element does not exist.
58
- */
59
- delete(key: TKey): boolean;
60
- /**
61
- * Returns a new Iterator object that contains the [key, value] pairs for each element.
62
- */
63
- entries(): IterableIterator<[TKey, TValue]>;
64
- /**
65
- * Same function object as the initial value of the entries method.
66
- */
67
- [Symbol.iterator](): IterableIterator<[TKey, TValue]>;
68
- /**
69
- * Returns a new Iterator object that contains the keys for each element.
70
- */
71
- keys(): IterableIterator<TKey>;
72
- /**
73
- * Returns a new Iterator object that contains the values for each element.
74
- */
75
- values(): IterableIterator<TValue>;
76
- /**
77
- * Executes a provided function once per each key/value pair in the Map object, in insertion order.
78
- * @param callback Function to execute for each entry in the map.
79
- */
80
- forEach(callback: (value: TValue, key: TKey, map: LiveMap<TKey, TValue>) => void): void;
241
+ declare class LiveRegister<TValue extends Json> extends AbstractCrdt {
242
+ constructor(data: TValue);
243
+ get data(): TValue;
81
244
  }
82
245
 
246
+ declare type LiveStructure =
247
+ | LiveObject<LsonObject>
248
+ | LiveList<Lson>
249
+ | LiveMap<string, Lson>;
83
250
  /**
84
251
  * Think of Lson as a sibling of the Json data tree, except that the nested
85
252
  * data structure can contain a mix of Json values and LiveStructure instances.
86
253
  */
87
- declare type Lson = Json | LiveObject<LsonObject> | LiveList<Lson> | LiveMap<string, Lson>;
254
+ declare type Lson = Json | LiveStructure;
255
+ /**
256
+ * LiveNode is the internal tree for managing Live data structures. The key
257
+ * difference with Lson is that all the Json values get represented in
258
+ * a LiveRegister node.
259
+ */
260
+ declare type LiveNode = LiveStructure | LiveRegister<Json>;
88
261
  /**
89
262
  * A mapping of keys to Lson values. A Lson value is any valid JSON
90
263
  * value or a Live storage data structure (LiveMap, LiveList, etc.)
91
264
  */
92
265
  declare type LsonObject = {
93
- [key: string]: Lson | undefined;
266
+ [key: string]: Lson | undefined;
94
267
  };
95
268
 
96
- /**
97
- * The LiveList class represents an ordered collection of items that is synchronized across clients.
98
- */
99
- declare class LiveList<TItem extends Lson = Lson> extends AbstractCrdt {
100
- private _items;
101
- constructor(items?: TItem[]);
102
- /**
103
- * Returns the number of elements.
104
- */
105
- get length(): number;
106
- /**
107
- * Adds one element to the end of the LiveList.
108
- * @param element The element to add to the end of the LiveList.
109
- */
110
- push(element: TItem): void;
111
- /**
112
- * Inserts one element at a specified index.
113
- * @param element The element to insert.
114
- * @param index The index at which you want to insert the element.
115
- */
116
- insert(element: TItem, index: number): void;
117
- /**
118
- * Move one element from one index to another.
119
- * @param index The index of the element to move
120
- * @param targetIndex The index where the element should be after moving.
121
- */
122
- move(index: number, targetIndex: number): void;
123
- /**
124
- * Deletes an element at the specified index
125
- * @param index The index of the element to delete
126
- */
127
- delete(index: number): void;
128
- clear(): void;
129
- set(index: number, item: TItem): void;
130
- /**
131
- * Returns an Array of all the elements in the LiveList.
132
- */
133
- toArray(): TItem[];
134
- /**
135
- * Tests whether all elements pass the test implemented by the provided function.
136
- * @param predicate Function to test for each element, taking two arguments (the element and its index).
137
- * @returns true if the predicate function returns a truthy value for every element. Otherwise, false.
138
- */
139
- every(predicate: (value: TItem, index: number) => unknown): boolean;
140
- /**
141
- * Creates an array with all elements that pass the test implemented by the provided function.
142
- * @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.
143
- * @returns An array with the elements that pass the test.
144
- */
145
- filter(predicate: (value: TItem, index: number) => unknown): TItem[];
146
- /**
147
- * Returns the first element that satisfies the provided testing function.
148
- * @param predicate Function to execute on each value.
149
- * @returns The value of the first element in the LiveList that satisfies the provided testing function. Otherwise, undefined is returned.
150
- */
151
- find(predicate: (value: TItem, index: number) => unknown): TItem | undefined;
152
- /**
153
- * Returns the index of the first element in the LiveList that satisfies the provided testing function.
154
- * @param predicate Function to execute on each value until the function returns true, indicating that the satisfying element was found.
155
- * @returns The index of the first element in the LiveList that passes the test. Otherwise, -1.
156
- */
157
- findIndex(predicate: (value: TItem, index: number) => unknown): number;
158
- /**
159
- * Executes a provided function once for each element.
160
- * @param callbackfn Function to execute on each element.
161
- */
162
- forEach(callbackfn: (value: TItem, index: number) => void): void;
163
- /**
164
- * Get the element at the specified index.
165
- * @param index The index on the element to get.
166
- * @returns The element at the specified index or undefined.
167
- */
168
- get(index: number): TItem | undefined;
169
- /**
170
- * Returns the first index at which a given element can be found in the LiveList, or -1 if it is not present.
171
- * @param searchElement Element to locate.
172
- * @param fromIndex The index to start the search at.
173
- * @returns The first index of the element in the LiveList; -1 if not found.
174
- */
175
- indexOf(searchElement: TItem, fromIndex?: number): number;
176
- /**
177
- * 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.
178
- * @param searchElement Element to locate.
179
- * @param fromIndex The index at which to start searching backwards.
180
- * @returns
181
- */
182
- lastIndexOf(searchElement: TItem, fromIndex?: number): number;
183
- /**
184
- * Creates an array populated with the results of calling a provided function on every element.
185
- * @param callback Function that is called for every element.
186
- * @returns An array with each element being the result of the callback function.
187
- */
188
- map<U>(callback: (value: TItem, index: number) => U): U[];
189
- /**
190
- * Tests whether at least one element in the LiveList passes the test implemented by the provided function.
191
- * @param predicate Function to test for each element.
192
- * @returns true if the callback function returns a truthy value for at least one element. Otherwise, false.
193
- */
194
- some(predicate: (value: TItem, index: number) => unknown): boolean;
195
- [Symbol.iterator](): IterableIterator<TItem>;
196
- }
197
-
198
269
  /**
199
270
  * This helper type is effectively a no-op, but will force TypeScript to
200
271
  * "evaluate" any named helper types in its definition. This can sometimes make
@@ -217,570 +288,568 @@ declare class LiveList<TItem extends Lson = Lson> extends AbstractCrdt {
217
288
  * This trick comes from:
218
289
  * https://effectivetypescript.com/2022/02/25/gentips-4-display/
219
290
  */
220
- declare type Resolve<T> = T extends Function ? T : {
221
- [K in keyof T]: T[K];
222
- };
223
- declare type MyPresenceCallback<T extends Presence = Presence> = (me: T) => void;
224
- declare type OthersEventCallback<T extends Presence = Presence> = (others: Others<T>, event: OthersEvent<T>) => void;
225
- declare type EventCallback = ({ connectionId, event, }: {
226
- connectionId: number;
227
- event: Json;
291
+ declare type Resolve<T> = T extends (...args: unknown[]) => unknown
292
+ ? T
293
+ : {
294
+ [K in keyof T]: T[K];
295
+ };
296
+ declare type MyPresenceCallback<TPresence extends JsonObject> = (
297
+ me: TPresence
298
+ ) => void;
299
+ declare type OthersEventCallback<
300
+ TPresence extends JsonObject,
301
+ TUserMeta extends BaseUserMeta
302
+ > = (
303
+ others: Others<TPresence, TUserMeta>,
304
+ event: OthersEvent<TPresence, TUserMeta>
305
+ ) => void;
306
+ declare type EventCallback<TEvent extends Json> = ({
307
+ connectionId,
308
+ event,
309
+ }: {
310
+ connectionId: number;
311
+ event: TEvent;
228
312
  }) => void;
229
313
  declare type ErrorCallback = (error: Error) => void;
230
314
  declare type ConnectionCallback = (state: ConnectionState) => void;
231
- declare type UpdateDelta = {
232
- type: "update";
233
- } | {
234
- type: "delete";
235
- };
315
+ declare type UpdateDelta =
316
+ | {
317
+ type: "update";
318
+ }
319
+ | {
320
+ type: "delete";
321
+ };
236
322
  /**
237
323
  * A LiveMap notification that is sent in-client to any subscribers whenever
238
324
  * one or more of the values inside the LiveMap instance have changed.
239
325
  */
240
326
  declare type LiveMapUpdates<TKey extends string, TValue extends Lson> = {
241
- type: "LiveMap";
242
- node: LiveMap<TKey, TValue>;
243
- updates: {
244
- [key: string]: UpdateDelta;
245
- };
327
+ type: "LiveMap";
328
+ node: LiveMap<TKey, TValue>;
329
+ updates: {
330
+ [key: string]: UpdateDelta;
331
+ };
246
332
  };
247
- declare type LiveObjectUpdateDelta<O extends {
333
+ declare type LiveObjectUpdateDelta<
334
+ O extends {
248
335
  [key: string]: unknown;
249
- }> = {
250
- [K in keyof O]?: UpdateDelta | undefined;
336
+ }
337
+ > = {
338
+ [K in keyof O]?: UpdateDelta | undefined;
251
339
  };
252
340
  /**
253
341
  * A LiveObject notification that is sent in-client to any subscribers whenever
254
342
  * one or more of the entries inside the LiveObject instance have changed.
255
343
  */
256
344
  declare type LiveObjectUpdates<TData extends LsonObject> = {
257
- type: "LiveObject";
258
- node: LiveObject<TData>;
259
- updates: LiveObjectUpdateDelta<TData>;
260
- };
261
- declare type LiveListUpdateDelta = {
262
- index: number;
263
- item: any;
264
- type: "insert";
265
- } | {
266
- index: number;
267
- type: "delete";
268
- } | {
269
- index: number;
270
- previousIndex: number;
271
- item: any;
272
- type: "move";
273
- } | {
274
- index: number;
275
- item: any;
276
- type: "set";
345
+ type: "LiveObject";
346
+ node: LiveObject<TData>;
347
+ updates: LiveObjectUpdateDelta<TData>;
277
348
  };
349
+ declare type LiveListUpdateDelta =
350
+ | {
351
+ index: number;
352
+ item: Lson;
353
+ type: "insert";
354
+ }
355
+ | {
356
+ index: number;
357
+ type: "delete";
358
+ }
359
+ | {
360
+ index: number;
361
+ previousIndex: number;
362
+ item: Lson;
363
+ type: "move";
364
+ }
365
+ | {
366
+ index: number;
367
+ item: Lson;
368
+ type: "set";
369
+ };
278
370
  /**
279
371
  * A LiveList notification that is sent in-client to any subscribers whenever
280
372
  * one or more of the items inside the LiveList instance have changed.
281
373
  */
282
374
  declare type LiveListUpdates<TItem extends Lson> = {
283
- type: "LiveList";
284
- node: LiveList<TItem>;
285
- updates: LiveListUpdateDelta[];
375
+ type: "LiveList";
376
+ node: LiveList<TItem>;
377
+ updates: LiveListUpdateDelta[];
286
378
  };
287
379
  declare type BroadcastOptions = {
288
- /**
289
- * Whether or not event is queued if the connection is currently closed.
290
- *
291
- * ❗ We are not sure if we want to support this option in the future so it might be deprecated to be replaced by something else
292
- */
293
- shouldQueueEventIfNotReady: boolean;
380
+ /**
381
+ * Whether or not event is queued if the connection is currently closed.
382
+ *
383
+ * ❗ We are not sure if we want to support this option in the future so it might be deprecated to be replaced by something else
384
+ */
385
+ shouldQueueEventIfNotReady: boolean;
294
386
  };
295
387
  /**
296
388
  * The payload of notifications sent (in-client) when LiveStructures change.
297
389
  * Messages of this kind are not originating from the network, but are 100%
298
390
  * in-client.
299
391
  */
300
- declare type StorageUpdate = LiveMapUpdates<string, Lson> | LiveObjectUpdates<LsonObject> | LiveListUpdates<Lson>;
301
- declare type RoomInitializers<TPresence, TStorage> = Resolve<{
302
- /**
303
- * The initial Presence to use and announce when you enter the Room. The
304
- * Presence is available on all users in the Room (me & others).
305
- */
306
- initialPresence?: TPresence | ((roomId: string) => TPresence);
307
- /**
308
- * The initial Storage to use when entering a new Room.
309
- */
310
- initialStorage?: TStorage | ((roomId: string) => TStorage);
311
- /**
312
- * @deprecated Please use `initialPresence` instead. This property is
313
- * scheduled for removal in 0.18.
314
- */
315
- defaultPresence?: () => TPresence;
316
- /**
317
- * @deprecated Please use `initialStorage` instead. This property is
318
- * scheduled for removal in 0.18.
319
- */
320
- defaultStorageRoot?: TStorage;
392
+ declare type StorageUpdate =
393
+ | LiveMapUpdates<string, Lson>
394
+ | LiveObjectUpdates<LsonObject>
395
+ | LiveListUpdates<Lson>;
396
+ declare type StorageCallback = (updates: StorageUpdate[]) => void;
397
+ declare type RoomInitializers<
398
+ TPresence extends JsonObject,
399
+ TStorage extends LsonObject
400
+ > = Resolve<{
401
+ /**
402
+ * The initial Presence to use and announce when you enter the Room. The
403
+ * Presence is available on all users in the Room (me & others).
404
+ */
405
+ initialPresence?: TPresence | ((roomId: string) => TPresence);
406
+ /**
407
+ * The initial Storage to use when entering a new Room.
408
+ */
409
+ initialStorage?: TStorage | ((roomId: string) => TStorage);
410
+ /**
411
+ * @deprecated Please use `initialPresence` instead. This property is
412
+ * scheduled for removal in 0.18.
413
+ */
414
+ defaultPresence?: () => TPresence;
415
+ /**
416
+ * @deprecated Please use `initialStorage` instead. This property is
417
+ * scheduled for removal in 0.18.
418
+ */
419
+ defaultStorageRoot?: TStorage;
321
420
  }>;
322
421
  declare type Client = {
323
- /**
324
- * Gets a room. Returns null if {@link Client.enter} has not been called previously.
325
- *
326
- * @param roomId The id of the room
327
- */
328
- getRoom(roomId: string): Room | null;
329
- /**
330
- * Enters a room and returns it.
331
- * @param roomId The id of the room
332
- * @param options Optional. You can provide initializers for the Presence or Storage when entering the Room.
333
- */
334
- enter<TStorage extends Record<string, any> = Record<string, any>>(roomId: string, options?: RoomInitializers<Presence, TStorage>): Room;
335
- /**
336
- * Leaves a room.
337
- * @param roomId The id of the room
338
- */
339
- leave(roomId: string): void;
422
+ /**
423
+ * Gets a room. Returns null if {@link Client.enter} has not been called previously.
424
+ *
425
+ * @param roomId The id of the room
426
+ */
427
+ getRoom<
428
+ TPresence extends JsonObject,
429
+ TStorage extends LsonObject,
430
+ TUserMeta extends BaseUserMeta,
431
+ TEvent extends Json
432
+ >(
433
+ roomId: string
434
+ ): Room<TPresence, TStorage, TUserMeta, TEvent> | null;
435
+ /**
436
+ * Enters a room and returns it.
437
+ * @param roomId The id of the room
438
+ * @param options Optional. You can provide initializers for the Presence or Storage when entering the Room.
439
+ */
440
+ enter<
441
+ TPresence extends JsonObject,
442
+ TStorage extends LsonObject,
443
+ TUserMeta extends BaseUserMeta,
444
+ TEvent extends Json
445
+ >(
446
+ roomId: string,
447
+ options?: RoomInitializers<TPresence, TStorage>
448
+ ): Room<TPresence, TStorage, TUserMeta, TEvent>;
449
+ /**
450
+ * Leaves a room.
451
+ * @param roomId The id of the room
452
+ */
453
+ leave(roomId: string): void;
340
454
  };
341
455
  /**
342
456
  * Represents all the other users connected in the room. Treated as immutable.
343
457
  */
344
- interface Others<TPresence extends Presence = Presence> {
345
- /**
346
- * Number of other users in the room.
347
- */
348
- readonly count: number;
349
- /**
350
- * Returns a new Iterator object that contains the users.
351
- */
352
- [Symbol.iterator](): IterableIterator<User<TPresence>>;
353
- /**
354
- * Returns the array of connected users in room.
355
- */
356
- toArray(): User<TPresence>[];
357
- /**
358
- * This function let you map over the connected users in the room.
359
- */
360
- map<U>(callback: (user: User<TPresence>) => U): U[];
458
+ interface Others<TPresence extends JsonObject, TUserMeta extends BaseUserMeta> {
459
+ /**
460
+ * Number of other users in the room.
461
+ */
462
+ readonly count: number;
463
+ /**
464
+ * Returns a new Iterator object that contains the users.
465
+ */
466
+ [Symbol.iterator](): IterableIterator<User<TPresence, TUserMeta>>;
467
+ /**
468
+ * Returns the array of connected users in room.
469
+ */
470
+ toArray(): User<TPresence, TUserMeta>[];
471
+ /**
472
+ * This function let you map over the connected users in the room.
473
+ */
474
+ map<U>(callback: (user: User<TPresence, TUserMeta>) => U): U[];
361
475
  }
362
476
  /**
363
477
  * Represents a user connected in a room. Treated as immutable.
364
478
  */
365
- declare type User<TPresence extends Presence = Presence> = {
366
- /**
367
- * The connection id of the user. It is unique and increment at every new connection.
368
- */
369
- readonly connectionId: number;
370
- /**
371
- * The id of the user that has been set in the authentication endpoint.
372
- * Useful to get additional information about the connected user.
373
- */
374
- readonly id?: string;
375
- /**
376
- * Additional user information that has been set in the authentication endpoint.
377
- */
378
- readonly info?: any;
379
- /**
380
- * The user presence.
381
- */
382
- readonly presence?: TPresence;
479
+ declare type User<
480
+ TPresence extends JsonObject,
481
+ TUserMeta extends BaseUserMeta
482
+ > = {
483
+ /**
484
+ * The connection id of the user. It is unique and increment at every new connection.
485
+ */
486
+ readonly connectionId: number;
487
+ /**
488
+ * The id of the user that has been set in the authentication endpoint.
489
+ * Useful to get additional information about the connected user.
490
+ */
491
+ readonly id: TUserMeta["id"];
492
+ /**
493
+ * Additional user information that has been set in the authentication endpoint.
494
+ */
495
+ readonly info: TUserMeta["info"];
496
+ /**
497
+ * The user presence.
498
+ */
499
+ readonly presence?: TPresence;
383
500
  };
384
- declare type Presence = Record<string, unknown>;
501
+ /**
502
+ * @deprecated Whatever you want to store as presence is app-specific. Please
503
+ * define your own Presence type instead of importing it from
504
+ * `@liveblocks/client`, for example:
505
+ *
506
+ * type Presence = {
507
+ * name: string,
508
+ * cursor: {
509
+ * x: number,
510
+ * y: number,
511
+ * } | null,
512
+ * }
513
+ *
514
+ * As long as it only contains JSON-serializable values, you're good!
515
+ */
516
+ declare type Presence = JsonObject;
385
517
  declare type AuthEndpointCallback = (room: string) => Promise<{
386
- token: string;
518
+ token: string;
387
519
  }>;
388
520
  declare type AuthEndpoint = string | AuthEndpointCallback;
521
+ declare type Polyfills = {
522
+ atob?: (data: string) => string;
523
+ fetch?: typeof fetch;
524
+ WebSocket?: any;
525
+ };
389
526
  /**
390
527
  * The authentication endpoint that is called to ensure that the current user has access to a room.
391
528
  * Can be an url or a callback if you need to add additional headers.
392
529
  */
393
530
  declare type ClientOptions = {
394
- throttle?: number;
395
- fetchPolyfill?: any;
396
- WebSocketPolyfill?: any;
397
- } & ({
398
- publicApiKey: string;
399
- authEndpoint?: never;
400
- } | {
401
- publicApiKey?: never;
402
- authEndpoint: AuthEndpoint;
403
- });
404
- declare type Connection = {
405
- state: "closed" | "authenticating" | "unavailable" | "failed";
406
- } | {
407
- state: "open" | "connecting";
408
- id: number;
409
- userId?: string;
410
- userInfo?: any;
411
- };
531
+ throttle?: number;
532
+ polyfills?: Polyfills;
533
+ /**
534
+ * Backward-compatible way to set `polyfills.fetch`.
535
+ */
536
+ fetchPolyfill?: Polyfills["fetch"];
537
+ /**
538
+ * Backward-compatible way to set `polyfills.WebSocket`.
539
+ */
540
+ WebSocketPolyfill?: Polyfills["WebSocket"];
541
+ } & (
542
+ | {
543
+ publicApiKey: string;
544
+ authEndpoint?: never;
545
+ }
546
+ | {
547
+ publicApiKey?: never;
548
+ authEndpoint: AuthEndpoint;
549
+ }
550
+ );
551
+ declare type Connection =
552
+ | {
553
+ state: "closed" | "authenticating" | "unavailable" | "failed";
554
+ }
555
+ | {
556
+ state: "open" | "connecting";
557
+ id: number;
558
+ userId?: string;
559
+ userInfo?: Json;
560
+ };
412
561
  declare type ConnectionState = Connection["state"];
413
- declare type OthersEvent<T extends Presence = Presence> = {
414
- type: "leave";
415
- user: User<T>;
416
- } | {
417
- type: "enter";
418
- user: User<T>;
419
- } | {
420
- type: "update";
421
- user: User<T>;
422
- updates: Partial<T>;
423
- } | {
424
- type: "reset";
425
- };
562
+ declare type OthersEvent<
563
+ TPresence extends JsonObject,
564
+ TUserMeta extends BaseUserMeta
565
+ > =
566
+ | {
567
+ type: "leave";
568
+ user: User<TPresence, TUserMeta>;
569
+ }
570
+ | {
571
+ type: "enter";
572
+ user: User<TPresence, TUserMeta>;
573
+ }
574
+ | {
575
+ type: "update";
576
+ user: User<TPresence, TUserMeta>;
577
+ updates: Partial<TPresence>;
578
+ }
579
+ | {
580
+ type: "reset";
581
+ };
426
582
  interface History {
427
- /**
428
- * Undoes the last operation executed by the current client.
429
- * It does not impact operations made by other clients.
583
+ /**
584
+ * Undoes the last operation executed by the current client.
585
+ * It does not impact operations made by other clients.
586
+ *
587
+ * @example
588
+ * room.updatePresence({ selectedId: "xx" }, { addToHistory: true });
589
+ * room.updatePresence({ selectedId: "yy" }, { addToHistory: true });
590
+ * room.history.undo();
591
+ * // room.getPresence() equals { selectedId: "xx" }
592
+ */
593
+ undo: () => void;
594
+ /**
595
+ * Redoes the last operation executed by the current client.
596
+ * It does not impact operations made by other clients.
597
+ *
598
+ * @example
599
+ * room.updatePresence({ selectedId: "xx" }, { addToHistory: true });
600
+ * room.updatePresence({ selectedId: "yy" }, { addToHistory: true });
601
+ * room.history.undo();
602
+ * // room.getPresence() equals { selectedId: "xx" }
603
+ * room.history.redo();
604
+ * // room.getPresence() equals { selectedId: "yy" }
605
+ */
606
+ redo: () => void;
607
+ /**
608
+ * All future modifications made on the Room will be merged together to create a single history item until resume is called.
609
+ *
610
+ * @example
611
+ * room.updatePresence({ cursor: { x: 0, y: 0 } }, { addToHistory: true });
612
+ * room.history.pause();
613
+ * room.updatePresence({ cursor: { x: 1, y: 1 } }, { addToHistory: true });
614
+ * room.updatePresence({ cursor: { x: 2, y: 2 } }, { addToHistory: true });
615
+ * room.history.resume();
616
+ * room.history.undo();
617
+ * // room.getPresence() equals { cursor: { x: 0, y: 0 } }
618
+ */
619
+ pause: () => void;
620
+ /**
621
+ * Resumes history. Modifications made on the Room are not merged into a single history item anymore.
622
+ *
623
+ * @example
624
+ * room.updatePresence({ cursor: { x: 0, y: 0 } }, { addToHistory: true });
625
+ * room.history.pause();
626
+ * room.updatePresence({ cursor: { x: 1, y: 1 } }, { addToHistory: true });
627
+ * room.updatePresence({ cursor: { x: 2, y: 2 } }, { addToHistory: true });
628
+ * room.history.resume();
629
+ * room.history.undo();
630
+ * // room.getPresence() equals { cursor: { x: 0, y: 0 } }
631
+ */
632
+ resume: () => void;
633
+ }
634
+ declare type Room<
635
+ TPresence extends JsonObject,
636
+ TStorage extends LsonObject,
637
+ TUserMeta extends BaseUserMeta,
638
+ TEvent extends Json
639
+ > = {
640
+ /**
641
+ * The id of the room.
642
+ */
643
+ readonly id: string;
644
+ getConnectionState(): ConnectionState;
645
+ subscribe: {
646
+ /**
647
+ * Subscribe to the current user presence updates.
430
648
  *
431
- * @example
432
- * room.updatePresence({ selectedId: "xxx" }, { addToHistory: true });
433
- * room.updatePresence({ selectedId: "yyy" }, { addToHistory: true });
434
- * room.history.undo();
435
- * // room.getPresence() equals { selectedId: "xxx" }
436
- */
437
- undo: () => void;
438
- /**
439
- * Redoes the last operation executed by the current client.
440
- * It does not impact operations made by other clients.
649
+ * @param listener the callback that is called every time the current user presence is updated with {@link Room.updatePresence}.
441
650
  *
442
651
  * @example
443
- * room.updatePresence({ selectedId: "xxx" }, { addToHistory: true });
444
- * room.updatePresence({ selectedId: "yyy" }, { addToHistory: true });
445
- * room.history.undo();
446
- * // room.getPresence() equals { selectedId: "xxx" }
447
- * room.history.redo();
448
- * // room.getPresence() equals { selectedId: "yyy" }
652
+ * room.subscribe("my-presence", (presence) => {
653
+ * // Do something
654
+ * });
449
655
  */
450
- redo: () => void;
656
+ (type: "my-presence", listener: MyPresenceCallback<TPresence>): () => void;
451
657
  /**
452
- * All future modifications made on the Room will be merged together to create a single history item until resume is called.
658
+ * Subscribe to the other users updates.
453
659
  *
454
- * @example
455
- * room.updatePresence({ cursor: { x: 0, y: 0 } }, { addToHistory: true });
456
- * room.history.pause();
457
- * room.updatePresence({ cursor: { x: 1, y: 1 } }, { addToHistory: true });
458
- * room.updatePresence({ cursor: { x: 2, y: 2 } }, { addToHistory: true });
459
- * room.history.resume();
460
- * room.history.undo();
461
- * // room.getPresence() equals { cursor: { x: 0, y: 0 } }
462
- */
463
- pause: () => void;
464
- /**
465
- * Resumes history. Modifications made on the Room are not merged into a single history item anymore.
660
+ * @param listener the callback that is called when a user enters or leaves the room or when a user update its presence.
466
661
  *
467
662
  * @example
468
- * room.updatePresence({ cursor: { x: 0, y: 0 } }, { addToHistory: true });
469
- * room.history.pause();
470
- * room.updatePresence({ cursor: { x: 1, y: 1 } }, { addToHistory: true });
471
- * room.updatePresence({ cursor: { x: 2, y: 2 } }, { addToHistory: true });
472
- * room.history.resume();
473
- * room.history.undo();
474
- * // room.getPresence() equals { cursor: { x: 0, y: 0 } }
475
- */
476
- resume: () => void;
477
- }
478
- declare type Room = {
479
- /**
480
- * The id of the room.
481
- */
482
- readonly id: string;
483
- getConnectionState(): ConnectionState;
484
- subscribe: {
485
- /**
486
- * Subscribe to the current user presence updates.
487
- *
488
- * @param listener the callback that is called every time the current user presence is updated with {@link Room.updatePresence}.
489
- *
490
- * @example
491
- * room.subscribe("my-presence", (presence) => {
492
- * // Do something
493
- * });
494
- */
495
- <T extends Presence>(type: "my-presence", listener: MyPresenceCallback<T>): () => void;
496
- /**
497
- * Subscribe to the other users updates.
498
- *
499
- * @param listener the callback that is called when a user enters or leaves the room or when a user update its presence.
500
- *
501
- * @example
502
- * room.subscribe("others", (others) => {
503
- * // Do something
504
- * });
505
- */
506
- <T extends Presence>(type: "others", listener: OthersEventCallback<T>): () => void;
507
- /**
508
- * Subscribe to events broadcasted by {@link Room.broadcastEvent}
509
- *
510
- * @param listener the callback that is called when a user calls {@link Room.broadcastEvent}
511
- *
512
- * @example
513
- * room.subscribe("event", ({ event, connectionId }) => {
514
- * // Do something
515
- * });
516
- */
517
- (type: "event", listener: EventCallback): () => void;
518
- /**
519
- * Subscribe to errors thrown in the room.
520
- */
521
- (type: "error", listener: ErrorCallback): () => void;
522
- /**
523
- * Subscribe to connection state updates.
524
- */
525
- (type: "connection", listener: ConnectionCallback): () => void;
526
- /**
527
- * Subscribes to changes made on a {@link LiveMap}. Returns an unsubscribe function.
528
- * In a future version, we will also expose what exactly changed in the {@link LiveMap}.
529
- *
530
- * @param listener the callback this called when the {@link LiveMap} changes.
531
- *
532
- * @returns Unsubscribe function.
533
- *
534
- * @example
535
- * const liveMap = new LiveMap();
536
- * const unsubscribe = room.subscribe(liveMap, (liveMap) => { });
537
- * unsubscribe();
538
- */
539
- <TKey extends string, TValue extends Lson>(liveMap: LiveMap<TKey, TValue>, listener: (liveMap: LiveMap<TKey, TValue>) => void): () => void;
540
- /**
541
- * Subscribes to changes made on a {@link LiveObject}. Returns an unsubscribe function.
542
- * In a future version, we will also expose what exactly changed in the {@link LiveObject}.
543
- *
544
- * @param listener the callback this called when the {@link LiveObject} changes.
545
- *
546
- * @returns Unsubscribe function.
547
- *
548
- * @example
549
- * const liveObject = new LiveObject();
550
- * const unsubscribe = room.subscribe(liveObject, (liveObject) => { });
551
- * unsubscribe();
552
- */
553
- <TData extends JsonObject>(liveObject: LiveObject<TData>, callback: (liveObject: LiveObject<TData>) => void): () => void;
554
- /**
555
- * Subscribes to changes made on a {@link LiveList}. Returns an unsubscribe function.
556
- * In a future version, we will also expose what exactly changed in the {@link LiveList}.
557
- *
558
- * @param listener the callback this called when the {@link LiveList} changes.
559
- *
560
- * @returns Unsubscribe function.
561
- *
562
- * @example
563
- * const liveList = new LiveList();
564
- * const unsubscribe = room.subscribe(liveList, (liveList) => { });
565
- * unsubscribe();
566
- */
567
- <TItem extends Lson>(liveList: LiveList<TItem>, callback: (liveList: LiveList<TItem>) => void): () => void;
568
- /**
569
- * Subscribes to changes made on a {@link LiveMap} and all the nested data structures. Returns an unsubscribe function.
570
- * In a future version, we will also expose what exactly changed in the {@link LiveMap}.
571
- *
572
- * @param listener the callback this called when the {@link LiveMap} changes.
573
- *
574
- * @returns Unsubscribe function.
575
- *
576
- * @example
577
- * const liveMap = new LiveMap();
578
- * const unsubscribe = room.subscribe(liveMap, (liveMap) => { }, { isDeep: true });
579
- * unsubscribe();
580
- */
581
- <TKey extends string, TValue extends Lson>(liveMap: LiveMap<TKey, TValue>, callback: (updates: LiveMapUpdates<TKey, TValue>[]) => void, options: {
582
- isDeep: true;
583
- }): () => void;
584
- /**
585
- * Subscribes to changes made on a {@link LiveObject} and all the nested data structures. Returns an unsubscribe function.
586
- * In a future version, we will also expose what exactly changed in the {@link LiveObject}.
587
- *
588
- * @param listener the callback this called when the {@link LiveObject} changes.
589
- *
590
- * @returns Unsubscribe function.
591
- *
592
- * @example
593
- * const liveObject = new LiveObject();
594
- * const unsubscribe = room.subscribe(liveObject, (liveObject) => { }, { isDeep: true });
595
- * unsubscribe();
596
- */
597
- <TData extends LsonObject>(liveObject: LiveObject<TData>, callback: (updates: LiveObjectUpdates<TData>[]) => void, options: {
598
- isDeep: true;
599
- }): () => void;
600
- /**
601
- * Subscribes to changes made on a {@link LiveList} and all the nested data structures. Returns an unsubscribe function.
602
- * In a future version, we will also expose what exactly changed in the {@link LiveList}.
603
- *
604
- * @param listener the callback this called when the {@link LiveList} changes.
605
- *
606
- * @returns Unsubscribe function.
607
- *
608
- * @example
609
- * const liveList = new LiveList();
610
- * const unsubscribe = room.subscribe(liveList, (liveList) => { }, { isDeep: true });
611
- * unsubscribe();
612
- */
613
- <TItem extends Lson>(liveList: LiveList<TItem>, callback: (updates: LiveListUpdates<TItem>[]) => void, options: {
614
- isDeep: true;
615
- }): () => void;
616
- };
617
- /**
618
- * Room's history contains functions that let you undo and redo operation made on by the current client on the presence and storage.
619
- */
620
- history: History;
621
- /**
622
- * @deprecated use the callback returned by subscribe instead.
623
- * See v0.13 release notes for more information.
624
- * Will be removed in a future version.
663
+ * room.subscribe("others", (others) => {
664
+ * // Do something
665
+ * });
625
666
  */
626
- unsubscribe: {
627
- /**
628
- * @deprecated use the callback returned by subscribe instead.
629
- * See v0.13 release notes for more information.
630
- * Will be removed in a future version.
631
- */
632
- <T extends Presence>(type: "my-presence", listener: MyPresenceCallback<T>): void;
633
- /**
634
- * @deprecated use the callback returned by subscribe instead.
635
- * See v0.13 release notes for more information.
636
- * Will be removed in a future version.
637
- */
638
- <T extends Presence>(type: "others", listener: OthersEventCallback<T>): void;
639
- /**
640
- * @deprecated use the callback returned by subscribe instead.
641
- * See v0.13 release notes for more information.
642
- * Will be removed in a future version.
643
- */
644
- (type: "event", listener: EventCallback): void;
645
- /**
646
- * @deprecated use the callback returned by subscribe instead.
647
- * See v0.13 release notes for more information.
648
- * Will be removed in a future version.
649
- */
650
- (type: "error", listener: ErrorCallback): void;
651
- /**
652
- * @deprecated use the callback returned by subscribe instead.
653
- * See v0.13 release notes for more information.
654
- * Will be removed in a future version.
655
- */
656
- (type: "connection", listener: ConnectionCallback): void;
657
- };
667
+ (
668
+ type: "others",
669
+ listener: OthersEventCallback<TPresence, TUserMeta>
670
+ ): () => void;
658
671
  /**
659
- * Gets the current user.
660
- * Returns null if not it is not yet connected to the room.
672
+ * Subscribe to events broadcasted by {@link Room.broadcastEvent}
673
+ *
674
+ * @param listener the callback that is called when a user calls {@link Room.broadcastEvent}
661
675
  *
662
676
  * @example
663
- * const user = room.getSelf();
677
+ * room.subscribe("event", ({ event, connectionId }) => {
678
+ * // Do something
679
+ * });
664
680
  */
665
- getSelf<TPresence extends Presence = Presence>(): User<TPresence> | null;
681
+ (type: "event", listener: EventCallback<TEvent>): () => void;
666
682
  /**
667
- * Gets the presence of the current user.
668
- *
669
- * @example
670
- * const presence = room.getPresence();
683
+ * Subscribe to errors thrown in the room.
671
684
  */
672
- getPresence: <T extends Presence>() => T;
685
+ (type: "error", listener: ErrorCallback): () => void;
673
686
  /**
674
- * Gets all the other users in the room.
675
- *
676
- * @example
677
- * const others = room.getOthers();
687
+ * Subscribe to connection state updates.
678
688
  */
679
- getOthers: <T extends Presence>() => Others<T>;
689
+ (type: "connection", listener: ConnectionCallback): () => void;
680
690
  /**
681
- * Updates the presence of the current user. Only pass the properties you want to update. No need to send the full presence.
682
- * @param overrides A partial object that contains the properties you want to update.
683
- * @param overrides Optional object to configure the behavior of updatePresence.
691
+ * Subscribes to changes made on a Live structure. Returns an unsubscribe function.
692
+ * In a future version, we will also expose what exactly changed in the Live structure.
684
693
  *
685
- * @example
686
- * room.updatePresence({ x: 0 });
687
- * room.updatePresence({ y: 0 });
694
+ * @param callback The callback this called when the Live structure changes.
688
695
  *
689
- * const presence = room.getPresence();
690
- * // presence is equivalent to { x: 0, y: 0 }
691
- */
692
- updatePresence: <T extends Presence>(overrides: Partial<T>, options?: {
693
- /**
694
- * Whether or not the presence should have an impact on the undo/redo history.
695
- */
696
- addToHistory: boolean;
697
- }) => void;
698
- /**
699
- * Broadcasts an event to other users in the room. Event broadcasted to the room can be listened with {@link Room.subscribe}("event").
700
- * @param {any} event the event to broadcast. Should be serializable to JSON
696
+ * @returns Unsubscribe function.
701
697
  *
702
698
  * @example
703
- * // On client A
704
- * room.broadcastEvent({ type: "EMOJI", emoji: "🔥" });
699
+ * const liveMap = new LiveMap(); // Could also be LiveList or LiveObject
700
+ * const unsubscribe = room.subscribe(liveMap, (liveMap) => { });
701
+ * unsubscribe();
702
+ */
703
+ <L extends LiveStructure>(
704
+ liveStructure: L,
705
+ callback: (node: L) => void
706
+ ): () => void;
707
+ /**
708
+ * Subscribes to changes made on a Live structure and all the nested data
709
+ * structures. Returns an unsubscribe function. In a future version, we
710
+ * will also expose what exactly changed in the Live structure.
705
711
  *
706
- * // On client B
707
- * room.subscribe("event", ({ event }) => {
708
- * if(event.type === "EMOJI") {
709
- * // Do something
710
- * }
711
- * });
712
- */
713
- broadcastEvent: (event: JsonObject, options?: BroadcastOptions) => void;
714
- /**
715
- * Get the room's storage asynchronously.
716
- * The storage's root is a {@link LiveObject}.
712
+ * @param callback The callback this called when the Live structure, or any
713
+ * of its nested values, changes.
717
714
  *
718
- * @example
719
- * const { root } = await room.getStorage();
720
- */
721
- getStorage: <TStorage extends LsonObject>() => Promise<{
722
- root: LiveObject<TStorage>;
723
- }>;
724
- /**
725
- * Batches modifications made during the given function.
726
- * All the modifications are sent to other clients in a single message.
727
- * All the subscribers are called only after the batch is over.
728
- * All the modifications are merged in a single history item (undo/redo).
715
+ * @returns Unsubscribe function.
729
716
  *
730
717
  * @example
731
- * const { root } = await room.getStorage();
732
- * room.batch(() => {
733
- * root.set("x", 0);
734
- * room.updatePresence({ cursor: { x: 100, y: 100 }});
735
- * });
736
- */
737
- batch: (fn: () => void) => void;
718
+ * const liveMap = new LiveMap(); // Could also be LiveList or LiveObject
719
+ * const unsubscribe = room.subscribe(liveMap, (updates) => { }, { isDeep: true });
720
+ * unsubscribe();
721
+ */
722
+ <L extends LiveStructure>(
723
+ liveStructure: L,
724
+ callback: StorageCallback,
725
+ options: {
726
+ isDeep: true;
727
+ }
728
+ ): () => void;
729
+ };
730
+ /**
731
+ * Room's history contains functions that let you undo and redo operation made on by the current client on the presence and storage.
732
+ */
733
+ history: History;
734
+ /**
735
+ * Gets the current user.
736
+ * Returns null if not it is not yet connected to the room.
737
+ *
738
+ * @example
739
+ * const user = room.getSelf();
740
+ */
741
+ getSelf(): User<TPresence, TUserMeta> | null;
742
+ /**
743
+ * Gets the presence of the current user.
744
+ *
745
+ * @example
746
+ * const presence = room.getPresence();
747
+ */
748
+ getPresence: () => TPresence;
749
+ /**
750
+ * Gets all the other users in the room.
751
+ *
752
+ * @example
753
+ * const others = room.getOthers();
754
+ */
755
+ getOthers: () => Others<TPresence, TUserMeta>;
756
+ /**
757
+ * Updates the presence of the current user. Only pass the properties you want to update. No need to send the full presence.
758
+ * @param overrides A partial object that contains the properties you want to update.
759
+ * @param overrides Optional object to configure the behavior of updatePresence.
760
+ *
761
+ * @example
762
+ * room.updatePresence({ x: 0 });
763
+ * room.updatePresence({ y: 0 });
764
+ *
765
+ * const presence = room.getPresence();
766
+ * // presence is equivalent to { x: 0, y: 0 }
767
+ */
768
+ updatePresence: (
769
+ overrides: Partial<TPresence>,
770
+ options?: {
771
+ /**
772
+ * Whether or not the presence should have an impact on the undo/redo history.
773
+ */
774
+ addToHistory: boolean;
775
+ }
776
+ ) => void;
777
+ /**
778
+ * Broadcasts an event to other users in the room. Event broadcasted to the room can be listened with {@link Room.subscribe}("event").
779
+ * @param {any} event the event to broadcast. Should be serializable to JSON
780
+ *
781
+ * @example
782
+ * // On client A
783
+ * room.broadcastEvent({ type: "EMOJI", emoji: "🔥" });
784
+ *
785
+ * // On client B
786
+ * room.subscribe("event", ({ event }) => {
787
+ * if(event.type === "EMOJI") {
788
+ * // Do something
789
+ * }
790
+ * });
791
+ */
792
+ broadcastEvent: (event: TEvent, options?: BroadcastOptions) => void;
793
+ /**
794
+ * Get the room's storage asynchronously.
795
+ * The storage's root is a {@link LiveObject}.
796
+ *
797
+ * @example
798
+ * const { root } = await room.getStorage();
799
+ */
800
+ getStorage: () => Promise<{
801
+ root: LiveObject<TStorage>;
802
+ }>;
803
+ /**
804
+ * Batches modifications made during the given function.
805
+ * All the modifications are sent to other clients in a single message.
806
+ * All the subscribers are called only after the batch is over.
807
+ * All the modifications are merged in a single history item (undo/redo).
808
+ *
809
+ * @example
810
+ * const { root } = await room.getStorage();
811
+ * room.batch(() => {
812
+ * root.set("x", 0);
813
+ * room.updatePresence({ cursor: { x: 100, y: 100 }});
814
+ * });
815
+ */
816
+ batch: (fn: () => void) => void;
738
817
  };
739
-
740
- declare abstract class AbstractCrdt {
741
- private __parent?;
742
- private __doc?;
743
- private __id?;
744
- private __parentKey?;
745
- get roomId(): string | null;
746
- }
747
-
748
- /**
749
- * The LiveObject class is similar to a JavaScript object that is synchronized on all clients.
750
- * Keys should be a string, and values should be serializable to JSON.
751
- * If multiple clients update the same property simultaneously, the last modification received by the Liveblocks servers is the winner.
752
- */
753
- declare class LiveObject<O extends LsonObject = LsonObject> extends AbstractCrdt {
754
- private _map;
755
- private _propToLastUpdate;
756
- constructor(obj?: O);
757
- private _applyUpdate;
758
- private _applyDeleteObjectKey;
759
- /**
760
- * Transform the LiveObject into a javascript object
761
- */
762
- toObject(): O;
763
- /**
764
- * Adds or updates a property with a specified key and a value.
765
- * @param key The key of the property to add
766
- * @param value The value of the property to add
767
- */
768
- set<TKey extends keyof O>(key: TKey, value: O[TKey]): void;
769
- /**
770
- * Returns a specified property from the LiveObject.
771
- * @param key The key of the property to get
772
- */
773
- get<TKey extends keyof O>(key: TKey): O[TKey];
774
- /**
775
- * Deletes a key from the LiveObject
776
- * @param key The key of the property to delete
777
- */
778
- delete(key: keyof O): void;
779
- /**
780
- * Adds or updates multiple properties at once with an object.
781
- * @param overrides The object used to overrides properties
782
- */
783
- update(overrides: Partial<O>): void;
818
+ declare enum WebsocketCloseCodes {
819
+ CLOSE_ABNORMAL = 1006,
820
+ INVALID_MESSAGE_FORMAT = 4000,
821
+ NOT_ALLOWED = 4001,
822
+ MAX_NUMBER_OF_MESSAGES_PER_SECONDS = 4002,
823
+ MAX_NUMBER_OF_CONCURRENT_CONNECTIONS = 4003,
824
+ MAX_NUMBER_OF_MESSAGES_PER_DAY_PER_APP = 4004,
825
+ MAX_NUMBER_OF_CONCURRENT_CONNECTIONS_PER_ROOM = 4005,
826
+ CLOSE_WITHOUT_RETRY = 4999,
784
827
  }
785
828
 
786
- 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, isJsonArray as i, isJsonObject as j, isJsonScalar as k };
829
+ export {
830
+ BaseUserMeta as B,
831
+ ClientOptions as C,
832
+ History as H,
833
+ Json as J,
834
+ LiveList as L,
835
+ Others as O,
836
+ Presence as P,
837
+ Room as R,
838
+ StorageUpdate as S,
839
+ User as U,
840
+ WebsocketCloseCodes as W,
841
+ Client as a,
842
+ LiveMap as b,
843
+ LiveObject as c,
844
+ BroadcastOptions as d,
845
+ JsonObject as e,
846
+ LiveStructure as f,
847
+ Lson as g,
848
+ LsonObject as h,
849
+ LiveNode as i,
850
+ Resolve as j,
851
+ RoomInitializers as k,
852
+ isJsonArray as l,
853
+ isJsonObject as m,
854
+ isJsonScalar as n,
855
+ };