@liveblocks/core 2.8.2 → 2.9.0-rc1

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.
package/dist/index.d.mts CHANGED
@@ -5,19 +5,6 @@
5
5
  declare function detectDupes(pkgName: string, pkgVersion: string | false, // false if not built yet
6
6
  pkgFormat: string | false): void;
7
7
 
8
- declare type CustomAuthenticationResult = {
9
- token: string;
10
- error?: never;
11
- } | {
12
- token?: never;
13
- error: "forbidden";
14
- reason: string;
15
- } | {
16
- token?: never;
17
- error: string;
18
- reason: string;
19
- };
20
-
21
8
  /**
22
9
  * Represents an indefinitely deep arbitrary JSON data structure. There are
23
10
  * four types that make up the Json family:
@@ -41,211 +28,6 @@ declare function isJsonScalar(data: Json): data is JsonScalar;
41
28
  declare function isJsonArray(data: Json): data is JsonArray;
42
29
  declare function isJsonObject(data: Json): data is JsonObject;
43
30
 
44
- /**
45
- * Represents some constraints for user info. Basically read this as: "any JSON
46
- * object is fine, but _if_ it has a name field, it _must_ be a string."
47
- * (Ditto for avatar.)
48
- */
49
- declare type IUserInfo = {
50
- [key: string]: Json | undefined;
51
- name?: string;
52
- avatar?: string;
53
- };
54
- /**
55
- * This type is used by clients to define the metadata for a user.
56
- */
57
- declare type BaseUserMeta = {
58
- /**
59
- * The id of the user that has been set in the authentication endpoint.
60
- * Useful to get additional information about the connected user.
61
- */
62
- id?: string;
63
- /**
64
- * Additional user information that has been set in the authentication endpoint.
65
- */
66
- info?: IUserInfo;
67
- };
68
-
69
- declare type Callback<T> = (event: T) => void;
70
- declare type UnsubscribeCallback = () => void;
71
- declare type Observable<T> = {
72
- /**
73
- * Register a callback function to be called whenever the event source emits
74
- * an event.
75
- */
76
- subscribe(callback: Callback<T>): UnsubscribeCallback;
77
- /**
78
- * Register a one-time callback function to be called whenever the event
79
- * source emits an event. After the event fires, the callback is
80
- * auto-unsubscribed.
81
- */
82
- subscribeOnce(callback: Callback<T>): UnsubscribeCallback;
83
- /**
84
- * Returns a promise that will resolve when an event is emitted by this
85
- * event source. Optionally, specify a predicate that has to match. The first
86
- * event matching that predicate will then resolve the promise.
87
- */
88
- waitUntil(predicate?: (event: T) => boolean): Promise<T>;
89
- };
90
- declare type EventSource<T> = Observable<T> & {
91
- /**
92
- * Notify all subscribers about the event.
93
- */
94
- notify(event: T): void;
95
- /**
96
- * Returns the number of active subscribers.
97
- */
98
- count(): number;
99
- /**
100
- * Pauses event delivery until unpaused. Any .notify() calls made while
101
- * paused will get buffered into memory and emitted later.
102
- */
103
- pause(): void;
104
- /**
105
- * Emits all in-memory buffered events, and unpauses. Any .notify() calls
106
- * made after this will be synchronously delivered again.
107
- */
108
- unpause(): void;
109
- /**
110
- * Observable instance, which can be used to subscribe to this event source
111
- * in a readonly fashion. Safe to publicly expose.
112
- */
113
- observable: Observable<T>;
114
- };
115
- /**
116
- * makeEventSource allows you to generate a subscribe/notify pair of functions
117
- * to make subscribing easy and to get notified about events.
118
- *
119
- * The events are anonymous, so you can use it to define events, like so:
120
- *
121
- * const event1 = makeEventSource();
122
- * const event2 = makeEventSource();
123
- *
124
- * event1.subscribe(foo);
125
- * event1.subscribe(bar);
126
- * event2.subscribe(qux);
127
- *
128
- * // Unsubscription is pretty standard
129
- * const unsub = event2.subscribe(foo);
130
- * unsub();
131
- *
132
- * event1.notify(); // Now foo and bar will get called
133
- * event2.notify(); // Now qux will get called (but foo will not, since it's unsubscribed)
134
- *
135
- */
136
- declare function makeEventSource<T>(): EventSource<T>;
137
-
138
- interface IWebSocketEvent {
139
- type: string;
140
- }
141
- interface IWebSocketCloseEvent extends IWebSocketEvent {
142
- readonly code: WebsocketCloseCodes;
143
- readonly wasClean: boolean;
144
- readonly reason: string;
145
- }
146
- interface IWebSocketMessageEvent extends IWebSocketEvent {
147
- readonly data: string | Buffer | ArrayBuffer | readonly Buffer[];
148
- }
149
- interface IWebSocketInstance {
150
- readonly CONNECTING: number;
151
- readonly OPEN: number;
152
- readonly CLOSING: number;
153
- readonly CLOSED: number;
154
- readonly readyState: number;
155
- addEventListener(type: "close", listener: (this: IWebSocketInstance, ev: IWebSocketCloseEvent) => unknown): void;
156
- addEventListener(type: "message", listener: (this: IWebSocketInstance, ev: IWebSocketMessageEvent) => unknown): void;
157
- addEventListener(type: "open" | "error", listener: (this: IWebSocketInstance, ev: IWebSocketEvent) => unknown): void;
158
- removeEventListener(type: "close", listener: (this: IWebSocketInstance, ev: IWebSocketCloseEvent) => unknown): void;
159
- removeEventListener(type: "message", listener: (this: IWebSocketInstance, ev: IWebSocketMessageEvent) => unknown): void;
160
- removeEventListener(type: "open" | "error", listener: (this: IWebSocketInstance, ev: IWebSocketEvent) => unknown): void;
161
- close(): void;
162
- send(data: string): void;
163
- }
164
- /**
165
- * Either the browser-based WebSocket API or Node.js' WebSocket API (from the
166
- * 'ws' package).
167
- *
168
- * This type defines the minimal WebSocket API that Liveblocks needs from
169
- * a WebSocket implementation, and is a minimal subset of the browser-based
170
- * WebSocket APIs and Node.js' WebSocket API so that both implementations are
171
- * assignable to this type.
172
- */
173
- interface IWebSocket {
174
- new (address: string): IWebSocketInstance;
175
- }
176
- /**
177
- * The following ranges will be respected by the client:
178
- *
179
- * 10xx: client will reauthorize (just like 41xx)
180
- * 40xx: client will disconnect
181
- * 41xx: client will reauthorize
182
- * 42xx: client will retry without reauthorizing (currently not used)
183
- *
184
- */
185
- declare enum WebsocketCloseCodes {
186
- /** Normal close of connection, the connection fulfilled its purpose. */
187
- CLOSE_NORMAL = 1000,
188
- /** Unexpected error happened with the network/infra level. In spirit akin to HTTP 503 */
189
- CLOSE_ABNORMAL = 1006,
190
- /** Unexpected error happened. In spirit akin to HTTP 500 */
191
- UNEXPECTED_CONDITION = 1011,
192
- /** Please back off for now, but try again in a few moments */
193
- TRY_AGAIN_LATER = 1013,
194
- /** Message wasn't understood, disconnect */
195
- INVALID_MESSAGE_FORMAT = 4000,
196
- /** Server refused to allow connection. Re-authorizing won't help. Disconnect. In spirit akin to HTTP 403 */
197
- NOT_ALLOWED = 4001,
198
- /** Unused */
199
- MAX_NUMBER_OF_MESSAGES_PER_SECONDS = 4002,
200
- /** Unused */
201
- MAX_NUMBER_OF_CONCURRENT_CONNECTIONS = 4003,
202
- /** Unused */
203
- MAX_NUMBER_OF_MESSAGES_PER_DAY_PER_APP = 4004,
204
- /** Room is full, disconnect */
205
- MAX_NUMBER_OF_CONCURRENT_CONNECTIONS_PER_ROOM = 4005,
206
- /** The room's ID was updated, disconnect */
207
- ROOM_ID_UPDATED = 4006,
208
- /** The server kicked the connection from the room. */
209
- KICKED = 4100,
210
- /** The auth token is expired, reauthorize to get a fresh one. In spirit akin to HTTP 401 */
211
- TOKEN_EXPIRED = 4109,
212
- /** Disconnect immediately */
213
- CLOSE_WITHOUT_RETRY = 4999
214
- }
215
-
216
- /**
217
- * Returns a human-readable status indicating the current connection status of
218
- * a Room, as returned by `room.getStatus()`. Can be used to implement
219
- * a connection status badge.
220
- */
221
- declare type Status = "initial" | "connecting" | "connected" | "reconnecting" | "disconnected";
222
- /**
223
- * Used to report about app-level reconnection issues.
224
- *
225
- * Normal (quick) reconnects won't be reported as a "lost connection". Instead,
226
- * the application will only get an event if the reconnection attempts by the
227
- * client are taking (much) longer than usual. Definitely a situation you want
228
- * to inform your users about, for example, by throwing a toast message on
229
- * screen, or show a "trying to reconnect" banner.
230
- */
231
- declare type LostConnectionEvent = "lost" | "restored" | "failed";
232
- /**
233
- * Arbitrary record that will be used as the authentication "authValue". It's the
234
- * value that is returned by calling the authentication delegate, and will get
235
- * passed to the connection factory delegate. This value will be remembered by
236
- * the connection manager, but its value will not be interpreted, so it can be
237
- * any value (except null).
238
- */
239
- declare type BaseAuthResult = NonNullable<Json>;
240
- declare class LiveblocksError extends Error {
241
- code: number;
242
- }
243
- declare type Delegates<T extends BaseAuthResult> = {
244
- authenticate: () => Promise<T>;
245
- createSocket: (authValue: T) => IWebSocketInstance;
246
- canZombie: () => boolean;
247
- };
248
-
249
31
  declare enum OpCode {
250
32
  INIT = 0,
251
33
  SET_PARENT_KEY = 1,
@@ -424,33 +206,83 @@ declare type PlainLsonList = {
424
206
  };
425
207
  declare type PlainLson = PlainLsonObject | PlainLsonMap | PlainLsonList | Json;
426
208
 
209
+ declare type LiveObjectUpdateDelta<O extends {
210
+ [key: string]: unknown;
211
+ }> = {
212
+ [K in keyof O]?: UpdateDelta | undefined;
213
+ };
427
214
  /**
428
- * Helper type to convert any valid Lson type to the equivalent Json type.
429
- *
430
- * Examples:
431
- *
432
- * ToImmutable<42> // 42
433
- * ToImmutable<'hi'> // 'hi'
434
- * ToImmutable<number> // number
435
- * ToImmutable<string> // string
436
- * ToImmutable<string | LiveList<number>> // string | readonly number[]
437
- * ToImmutable<LiveMap<string, LiveList<number>>>
438
- * // ReadonlyMap<string, readonly number[]>
439
- * ToImmutable<LiveObject<{ a: number, b: LiveList<string>, c?: number }>>
440
- * // { readonly a: null, readonly b: readonly string[], readonly c?: number }
441
- *
215
+ * A LiveObject notification that is sent in-client to any subscribers whenever
216
+ * one or more of the entries inside the LiveObject instance have changed.
442
217
  */
443
- declare type ToImmutable<L extends Lson | LsonObject> = L extends LiveList<infer I> ? readonly ToImmutable<I>[] : L extends LiveObject<infer O> ? ToImmutable<O> : L extends LiveMap<infer K, infer V> ? ReadonlyMap<K, ToImmutable<V>> : L extends LsonObject ? {
444
- readonly [K in keyof L]: ToImmutable<Exclude<L[K], undefined>> | (undefined extends L[K] ? undefined : never);
445
- } : L extends Json ? L : never;
218
+ declare type LiveObjectUpdates<TData extends LsonObject> = {
219
+ type: "LiveObject";
220
+ node: LiveObject<TData>;
221
+ updates: LiveObjectUpdateDelta<TData>;
222
+ };
446
223
  /**
447
- * Returns PlainLson for a given Json or LiveStructure, suitable for calling the storage init api
224
+ * The LiveObject class is similar to a JavaScript object that is synchronized on all clients.
225
+ * Keys should be a string, and values should be serializable to JSON.
226
+ * If multiple clients update the same property simultaneously, the last modification received by the Liveblocks servers is the winner.
448
227
  */
449
- declare function toPlainLson(lson: Lson): PlainLson;
450
-
451
- /**
452
- * A LiveMap notification that is sent in-client to any subscribers whenever
453
- * one or more of the values inside the LiveMap instance have changed.
228
+ declare class LiveObject<O extends LsonObject> extends AbstractCrdt {
229
+ constructor(obj?: O);
230
+ /**
231
+ * Transform the LiveObject into a javascript object
232
+ */
233
+ toObject(): O;
234
+ /**
235
+ * Adds or updates a property with a specified key and a value.
236
+ * @param key The key of the property to add
237
+ * @param value The value of the property to add
238
+ */
239
+ set<TKey extends keyof O>(key: TKey, value: O[TKey]): void;
240
+ /**
241
+ * Returns a specified property from the LiveObject.
242
+ * @param key The key of the property to get
243
+ */
244
+ get<TKey extends keyof O>(key: TKey): O[TKey];
245
+ /**
246
+ * Deletes a key from the LiveObject
247
+ * @param key The key of the property to delete
248
+ */
249
+ delete(key: keyof O): void;
250
+ /**
251
+ * Adds or updates multiple properties at once with an object.
252
+ * @param patch The object used to overrides properties
253
+ */
254
+ update(patch: Partial<O>): void;
255
+ toImmutable(): ToImmutable<O>;
256
+ clone(): LiveObject<O>;
257
+ }
258
+
259
+ /**
260
+ * Helper type to convert any valid Lson type to the equivalent Json type.
261
+ *
262
+ * Examples:
263
+ *
264
+ * ToImmutable<42> // 42
265
+ * ToImmutable<'hi'> // 'hi'
266
+ * ToImmutable<number> // number
267
+ * ToImmutable<string> // string
268
+ * ToImmutable<string | LiveList<number>> // string | readonly number[]
269
+ * ToImmutable<LiveMap<string, LiveList<number>>>
270
+ * // ReadonlyMap<string, readonly number[]>
271
+ * ToImmutable<LiveObject<{ a: number, b: LiveList<string>, c?: number }>>
272
+ * // { readonly a: null, readonly b: readonly string[], readonly c?: number }
273
+ *
274
+ */
275
+ declare type ToImmutable<L extends Lson | LsonObject> = L extends LiveList<infer I> ? readonly ToImmutable<I>[] : L extends LiveObject<infer O> ? ToImmutable<O> : L extends LiveMap<infer K, infer V> ? ReadonlyMap<K, ToImmutable<V>> : L extends LsonObject ? {
276
+ readonly [K in keyof L]: ToImmutable<Exclude<L[K], undefined>> | (undefined extends L[K] ? undefined : never);
277
+ } : L extends Json ? L : never;
278
+ /**
279
+ * Returns PlainLson for a given Json or LiveStructure, suitable for calling the storage init api
280
+ */
281
+ declare function toPlainLson(lson: Lson): PlainLson;
282
+
283
+ /**
284
+ * A LiveMap notification that is sent in-client to any subscribers whenever
285
+ * one or more of the values inside the LiveMap instance have changed.
454
286
  */
455
287
  declare type LiveMapUpdates<TKey extends string, TValue extends Lson> = {
456
288
  type: "LiveMap";
@@ -721,56 +553,6 @@ declare type ToJson<T extends Lson | LsonObject> = T extends Json ? T : T extend
721
553
  [K in KS]: ToJson<V>;
722
554
  } : never;
723
555
 
724
- declare type LiveObjectUpdateDelta<O extends {
725
- [key: string]: unknown;
726
- }> = {
727
- [K in keyof O]?: UpdateDelta | undefined;
728
- };
729
- /**
730
- * A LiveObject notification that is sent in-client to any subscribers whenever
731
- * one or more of the entries inside the LiveObject instance have changed.
732
- */
733
- declare type LiveObjectUpdates<TData extends LsonObject> = {
734
- type: "LiveObject";
735
- node: LiveObject<TData>;
736
- updates: LiveObjectUpdateDelta<TData>;
737
- };
738
- /**
739
- * The LiveObject class is similar to a JavaScript object that is synchronized on all clients.
740
- * Keys should be a string, and values should be serializable to JSON.
741
- * If multiple clients update the same property simultaneously, the last modification received by the Liveblocks servers is the winner.
742
- */
743
- declare class LiveObject<O extends LsonObject> extends AbstractCrdt {
744
- constructor(obj?: O);
745
- /**
746
- * Transform the LiveObject into a javascript object
747
- */
748
- toObject(): O;
749
- /**
750
- * Adds or updates a property with a specified key and a value.
751
- * @param key The key of the property to add
752
- * @param value The value of the property to add
753
- */
754
- set<TKey extends keyof O>(key: TKey, value: O[TKey]): void;
755
- /**
756
- * Returns a specified property from the LiveObject.
757
- * @param key The key of the property to get
758
- */
759
- get<TKey extends keyof O>(key: TKey): O[TKey];
760
- /**
761
- * Deletes a key from the LiveObject
762
- * @param key The key of the property to delete
763
- */
764
- delete(key: keyof O): void;
765
- /**
766
- * Adds or updates multiple properties at once with an object.
767
- * @param patch The object used to overrides properties
768
- */
769
- update(patch: Partial<O>): void;
770
- toImmutable(): ToImmutable<O>;
771
- clone(): LiveObject<O>;
772
- }
773
-
774
556
  declare type DateToString<T> = {
775
557
  [P in keyof T]: T[P] extends Date ? string : T[P] extends Date | null ? string | null : T[P] extends Date | undefined ? string | undefined : T[P];
776
558
  };
@@ -837,6 +619,31 @@ declare type BaseRoomInfo = {
837
619
  url?: string;
838
620
  };
839
621
 
622
+ /**
623
+ * Represents some constraints for user info. Basically read this as: "any JSON
624
+ * object is fine, but _if_ it has a name field, it _must_ be a string."
625
+ * (Ditto for avatar.)
626
+ */
627
+ declare type IUserInfo = {
628
+ [key: string]: Json | undefined;
629
+ name?: string;
630
+ avatar?: string;
631
+ };
632
+ /**
633
+ * This type is used by clients to define the metadata for a user.
634
+ */
635
+ declare type BaseUserMeta = {
636
+ /**
637
+ * The id of the user that has been set in the authentication endpoint.
638
+ * Useful to get additional information about the connected user.
639
+ */
640
+ id?: string;
641
+ /**
642
+ * Additional user information that has been set in the authentication endpoint.
643
+ */
644
+ info?: IUserInfo;
645
+ };
646
+
840
647
  declare type BaseMetadata = Record<string, string | boolean | number | undefined>;
841
648
  declare type CommentReaction = {
842
649
  emoji: string;
@@ -954,111 +761,350 @@ declare type CommentUserReaction = {
954
761
  };
955
762
  declare type CommentUserReactionPlain = DateToString<CommentUserReaction>;
956
763
  /**
957
- * Represents a thread of comments.
764
+ * Represents a thread of comments.
765
+ */
766
+ declare type ThreadData<M extends BaseMetadata = DM> = {
767
+ type: "thread";
768
+ id: string;
769
+ roomId: string;
770
+ createdAt: Date;
771
+ updatedAt?: Date;
772
+ comments: CommentData[];
773
+ metadata: M;
774
+ resolved: boolean;
775
+ };
776
+ interface ThreadDataWithDeleteInfo<M extends BaseMetadata = DM> extends ThreadData<M> {
777
+ deletedAt?: Date;
778
+ }
779
+ declare type ThreadDataPlain<M extends BaseMetadata> = Omit<DateToString<ThreadData<M>>, "comments" | "metadata"> & {
780
+ comments: CommentDataPlain[];
781
+ metadata: M;
782
+ };
783
+ declare type ThreadDeleteInfo = {
784
+ type: "deletedThread";
785
+ id: string;
786
+ roomId: string;
787
+ deletedAt: Date;
788
+ };
789
+ declare type StringOperators<T> = T | {
790
+ startsWith: string;
791
+ };
792
+ /**
793
+ * This type can be used to build a metadata query string (compatible
794
+ * with `@liveblocks/query-parser`) through a type-safe API.
795
+ *
796
+ * In addition to exact values (`:` in query string), it adds:
797
+ * - to strings:
798
+ * - `startsWith` (`^` in query string)
799
+ */
800
+ declare type QueryMetadata<M extends BaseMetadata> = {
801
+ [K in keyof M]: string extends M[K] ? StringOperators<M[K]> : M[K];
802
+ };
803
+
804
+ declare global {
805
+ /**
806
+ * Namespace for user-defined Liveblocks types.
807
+ */
808
+ export interface Liveblocks {
809
+ [key: string]: unknown;
810
+ }
811
+ }
812
+ declare type ExtendableTypes = "Presence" | "Storage" | "UserMeta" | "RoomEvent" | "ThreadMetadata" | "RoomInfo" | "ActivitiesData";
813
+ declare type MakeErrorString<K extends ExtendableTypes, Reason extends string = "does not match its requirements"> = `The type you provided for '${K}' ${Reason}. To learn how to fix this, see https://liveblocks.io/docs/errors/${K}`;
814
+ declare type GetOverride<K extends ExtendableTypes, B, Reason extends string = "does not match its requirements"> = GetOverrideOrErrorValue<K, B, MakeErrorString<K, Reason>>;
815
+ declare type GetOverrideOrErrorValue<K extends ExtendableTypes, B, ErrorType> = unknown extends Liveblocks[K] ? B : Liveblocks[K] extends B ? Liveblocks[K] : ErrorType;
816
+ declare type DP = GetOverride<"Presence", JsonObject, "is not a valid JSON object">;
817
+ declare type DS = GetOverride<"Storage", LsonObject, "is not a valid LSON value">;
818
+ declare type DU = GetOverrideOrErrorValue<"UserMeta", BaseUserMeta, Record<"id" | "info", MakeErrorString<"UserMeta">>>;
819
+ declare type DE = GetOverride<"RoomEvent", Json, "is not a valid JSON value">;
820
+ declare type DM = GetOverride<"ThreadMetadata", BaseMetadata>;
821
+ declare type DRI = GetOverride<"RoomInfo", BaseRoomInfo>;
822
+ declare type DAD = GetOverrideOrErrorValue<"ActivitiesData", BaseActivitiesData, {
823
+ [K in keyof Liveblocks["ActivitiesData"]]: "At least one of the custom notification kinds you provided for 'ActivitiesData' does not match its requirements. To learn how to fix this, see https://liveblocks.io/docs/errors/ActivitiesData";
824
+ }>;
825
+ declare type KDAD = keyof DAD extends `$${string}` ? keyof DAD : "Custom notification kinds must start with '$' but your custom 'ActivitiesData' type contains at least one kind which doesn't. To learn how to fix this, see https://liveblocks.io/docs/errors/ActivitiesData";
826
+
827
+ /**
828
+ * Use this symbol to brand an object property as internal.
829
+ *
830
+ * @example
831
+ * Object.defineProperty(
832
+ * {
833
+ * public,
834
+ * [kInternal]: {
835
+ * private
836
+ * },
837
+ * },
838
+ * kInternal,
839
+ * {
840
+ * enumerable: false,
841
+ * }
842
+ * );
843
+ */
844
+ declare const kInternal: unique symbol;
845
+
846
+ declare type RenameDataField<T, TFieldName extends string> = T extends any ? {
847
+ [K in keyof T as K extends "data" ? TFieldName : K]: T[K];
848
+ } : never;
849
+ declare type AsyncLoading<F extends string = "data"> = RenameDataField<{
850
+ readonly isLoading: true;
851
+ readonly data?: never;
852
+ readonly error?: never;
853
+ }, F>;
854
+ declare type AsyncSuccess<T, F extends string = "data"> = RenameDataField<{
855
+ readonly isLoading: false;
856
+ readonly data: T;
857
+ readonly error?: never;
858
+ }, F>;
859
+ declare type AsyncError<F extends string = "data"> = RenameDataField<{
860
+ readonly isLoading: false;
861
+ readonly data?: never;
862
+ readonly error: Error;
863
+ }, F>;
864
+ declare type AsyncResult<T, F extends string = "data"> = AsyncLoading<F> | AsyncSuccess<T, F> | AsyncError<F>;
865
+
866
+ declare type Callback<T> = (event: T) => void;
867
+ declare type UnsubscribeCallback = () => void;
868
+ declare type Observable<T> = {
869
+ /**
870
+ * Register a callback function to be called whenever the event source emits
871
+ * an event.
872
+ */
873
+ subscribe(callback: Callback<T>): UnsubscribeCallback;
874
+ /**
875
+ * Register a one-time callback function to be called whenever the event
876
+ * source emits an event. After the event fires, the callback is
877
+ * auto-unsubscribed.
878
+ */
879
+ subscribeOnce(callback: Callback<T>): UnsubscribeCallback;
880
+ /**
881
+ * Returns a promise that will resolve when an event is emitted by this
882
+ * event source. Optionally, specify a predicate that has to match. The first
883
+ * event matching that predicate will then resolve the promise.
884
+ */
885
+ waitUntil(predicate?: (event: T) => boolean): Promise<T>;
886
+ };
887
+ declare type EventSource<T> = Observable<T> & {
888
+ /**
889
+ * Notify all subscribers about the event.
890
+ */
891
+ notify(event: T): void;
892
+ /**
893
+ * Returns the number of active subscribers.
894
+ */
895
+ count(): number;
896
+ /**
897
+ * Pauses event delivery until unpaused. Any .notify() calls made while
898
+ * paused will get buffered into memory and emitted later.
899
+ */
900
+ pause(): void;
901
+ /**
902
+ * Emits all in-memory buffered events, and unpauses. Any .notify() calls
903
+ * made after this will be synchronously delivered again.
904
+ */
905
+ unpause(): void;
906
+ /**
907
+ * Observable instance, which can be used to subscribe to this event source
908
+ * in a readonly fashion. Safe to publicly expose.
909
+ */
910
+ observable: Observable<T>;
911
+ };
912
+ /**
913
+ * makeEventSource allows you to generate a subscribe/notify pair of functions
914
+ * to make subscribing easy and to get notified about events.
915
+ *
916
+ * The events are anonymous, so you can use it to define events, like so:
917
+ *
918
+ * const event1 = makeEventSource();
919
+ * const event2 = makeEventSource();
920
+ *
921
+ * event1.subscribe(foo);
922
+ * event1.subscribe(bar);
923
+ * event2.subscribe(qux);
924
+ *
925
+ * // Unsubscription is pretty standard
926
+ * const unsub = event2.subscribe(foo);
927
+ * unsub();
928
+ *
929
+ * event1.notify(); // Now foo and bar will get called
930
+ * event2.notify(); // Now qux will get called (but foo will not, since it's unsubscribed)
931
+ *
932
+ */
933
+ declare function makeEventSource<T>(): EventSource<T>;
934
+
935
+ declare type BatchStore<O, I> = Observable<void> & {
936
+ get: (input: I) => Promise<void>;
937
+ getState: (input: I) => AsyncResult<O> | undefined;
938
+ };
939
+
940
+ /**
941
+ * A Store is just a mini Zustand store.
942
+ */
943
+ declare type Store<T> = {
944
+ get: () => Readonly<T>;
945
+ set: (callback: (currentState: Readonly<T>) => Readonly<T>) => void;
946
+ subscribe: (callback: () => void) => () => void;
947
+ batch: (callback: () => void) => void;
948
+ };
949
+ /**
950
+ * Create a store for an immutable state. Close to Zustand's vanilla store conceptually but with less features.
951
+ */
952
+ declare function createStore<T>(initialState: T): Store<T>;
953
+
954
+ /**
955
+ * Back-port of TypeScript 5.4's built-in NoInfer utility type.
956
+ * See https://stackoverflow.com/a/56688073/148872
957
+ */
958
+ declare type NoInfr<A> = [A][A extends any ? 0 : never];
959
+
960
+ /**
961
+ * This helper type is effectively a no-op, but will force TypeScript to
962
+ * "evaluate" any named helper types in its definition. This can sometimes make
963
+ * API signatures clearer in IDEs.
964
+ *
965
+ * For example, in:
966
+ *
967
+ * type Payload<T> = { data: T };
968
+ *
969
+ * let r1: Payload<string>;
970
+ * let r2: Resolve<Payload<string>>;
971
+ *
972
+ * The inferred type of `r1` is going to be `Payload<string>` which shows up in
973
+ * editor hints, and it may be unclear what's inside if you don't know the
974
+ * definition of `Payload`.
975
+ *
976
+ * The inferred type of `r2` is going to be `{ data: string }`, which may be
977
+ * more helpful.
978
+ *
979
+ * This trick comes from:
980
+ * https://effectivetypescript.com/2022/02/25/gentips-4-display/
981
+ */
982
+ declare type Resolve<T> = T extends (...args: unknown[]) => unknown ? T : {
983
+ [K in keyof T]: T[K];
984
+ };
985
+
986
+ declare type CustomAuthenticationResult = {
987
+ token: string;
988
+ error?: never;
989
+ } | {
990
+ token?: never;
991
+ error: "forbidden";
992
+ reason: string;
993
+ } | {
994
+ token?: never;
995
+ error: string;
996
+ reason: string;
997
+ };
998
+
999
+ interface IWebSocketEvent {
1000
+ type: string;
1001
+ }
1002
+ interface IWebSocketCloseEvent extends IWebSocketEvent {
1003
+ readonly code: WebsocketCloseCodes;
1004
+ readonly wasClean: boolean;
1005
+ readonly reason: string;
1006
+ }
1007
+ interface IWebSocketMessageEvent extends IWebSocketEvent {
1008
+ readonly data: string | Buffer | ArrayBuffer | readonly Buffer[];
1009
+ }
1010
+ interface IWebSocketInstance {
1011
+ readonly CONNECTING: number;
1012
+ readonly OPEN: number;
1013
+ readonly CLOSING: number;
1014
+ readonly CLOSED: number;
1015
+ readonly readyState: number;
1016
+ addEventListener(type: "close", listener: (this: IWebSocketInstance, ev: IWebSocketCloseEvent) => unknown): void;
1017
+ addEventListener(type: "message", listener: (this: IWebSocketInstance, ev: IWebSocketMessageEvent) => unknown): void;
1018
+ addEventListener(type: "open" | "error", listener: (this: IWebSocketInstance, ev: IWebSocketEvent) => unknown): void;
1019
+ removeEventListener(type: "close", listener: (this: IWebSocketInstance, ev: IWebSocketCloseEvent) => unknown): void;
1020
+ removeEventListener(type: "message", listener: (this: IWebSocketInstance, ev: IWebSocketMessageEvent) => unknown): void;
1021
+ removeEventListener(type: "open" | "error", listener: (this: IWebSocketInstance, ev: IWebSocketEvent) => unknown): void;
1022
+ close(): void;
1023
+ send(data: string): void;
1024
+ }
1025
+ /**
1026
+ * Either the browser-based WebSocket API or Node.js' WebSocket API (from the
1027
+ * 'ws' package).
1028
+ *
1029
+ * This type defines the minimal WebSocket API that Liveblocks needs from
1030
+ * a WebSocket implementation, and is a minimal subset of the browser-based
1031
+ * WebSocket APIs and Node.js' WebSocket API so that both implementations are
1032
+ * assignable to this type.
958
1033
  */
959
- declare type ThreadData<M extends BaseMetadata = DM> = {
960
- type: "thread";
961
- id: string;
962
- roomId: string;
963
- createdAt: Date;
964
- updatedAt?: Date;
965
- comments: CommentData[];
966
- metadata: M;
967
- resolved: boolean;
968
- };
969
- interface ThreadDataWithDeleteInfo<M extends BaseMetadata = DM> extends ThreadData<M> {
970
- deletedAt?: Date;
1034
+ interface IWebSocket {
1035
+ new (address: string): IWebSocketInstance;
971
1036
  }
972
- declare type ThreadDataPlain<M extends BaseMetadata> = Omit<DateToString<ThreadData<M>>, "comments" | "metadata"> & {
973
- comments: CommentDataPlain[];
974
- metadata: M;
975
- };
976
- declare type ThreadDeleteInfo = {
977
- type: "deletedThread";
978
- id: string;
979
- roomId: string;
980
- deletedAt: Date;
981
- };
982
- declare type StringOperators<T> = T | {
983
- startsWith: string;
984
- };
985
1037
  /**
986
- * This type can be used to build a metadata query string (compatible
987
- * with `@liveblocks/query-parser`) through a type-safe API.
1038
+ * The following ranges will be respected by the client:
1039
+ *
1040
+ * 10xx: client will reauthorize (just like 41xx)
1041
+ * 40xx: client will disconnect
1042
+ * 41xx: client will reauthorize
1043
+ * 42xx: client will retry without reauthorizing (currently not used)
988
1044
  *
989
- * In addition to exact values (`:` in query string), it adds:
990
- * - to strings:
991
- * - `startsWith` (`^` in query string)
992
1045
  */
993
- declare type QueryMetadata<M extends BaseMetadata> = {
994
- [K in keyof M]: string extends M[K] ? StringOperators<M[K]> : M[K];
995
- };
996
-
997
- declare global {
998
- /**
999
- * Namespace for user-defined Liveblocks types.
1000
- */
1001
- export interface Liveblocks {
1002
- [key: string]: unknown;
1003
- }
1046
+ declare enum WebsocketCloseCodes {
1047
+ /** Normal close of connection, the connection fulfilled its purpose. */
1048
+ CLOSE_NORMAL = 1000,
1049
+ /** Unexpected error happened with the network/infra level. In spirit akin to HTTP 503 */
1050
+ CLOSE_ABNORMAL = 1006,
1051
+ /** Unexpected error happened. In spirit akin to HTTP 500 */
1052
+ UNEXPECTED_CONDITION = 1011,
1053
+ /** Please back off for now, but try again in a few moments */
1054
+ TRY_AGAIN_LATER = 1013,
1055
+ /** Message wasn't understood, disconnect */
1056
+ INVALID_MESSAGE_FORMAT = 4000,
1057
+ /** Server refused to allow connection. Re-authorizing won't help. Disconnect. In spirit akin to HTTP 403 */
1058
+ NOT_ALLOWED = 4001,
1059
+ /** Unused */
1060
+ MAX_NUMBER_OF_MESSAGES_PER_SECONDS = 4002,
1061
+ /** Unused */
1062
+ MAX_NUMBER_OF_CONCURRENT_CONNECTIONS = 4003,
1063
+ /** Unused */
1064
+ MAX_NUMBER_OF_MESSAGES_PER_DAY_PER_APP = 4004,
1065
+ /** Room is full, disconnect */
1066
+ MAX_NUMBER_OF_CONCURRENT_CONNECTIONS_PER_ROOM = 4005,
1067
+ /** The room's ID was updated, disconnect */
1068
+ ROOM_ID_UPDATED = 4006,
1069
+ /** The server kicked the connection from the room. */
1070
+ KICKED = 4100,
1071
+ /** The auth token is expired, reauthorize to get a fresh one. In spirit akin to HTTP 401 */
1072
+ TOKEN_EXPIRED = 4109,
1073
+ /** Disconnect immediately */
1074
+ CLOSE_WITHOUT_RETRY = 4999
1004
1075
  }
1005
- declare type ExtendableTypes = "Presence" | "Storage" | "UserMeta" | "RoomEvent" | "ThreadMetadata" | "RoomInfo" | "ActivitiesData";
1006
- declare type MakeErrorString<K extends ExtendableTypes, Reason extends string = "does not match its requirements"> = `The type you provided for '${K}' ${Reason}. To learn how to fix this, see https://liveblocks.io/docs/errors/${K}`;
1007
- declare type GetOverride<K extends ExtendableTypes, B, Reason extends string = "does not match its requirements"> = GetOverrideOrErrorValue<K, B, MakeErrorString<K, Reason>>;
1008
- declare type GetOverrideOrErrorValue<K extends ExtendableTypes, B, ErrorType> = unknown extends Liveblocks[K] ? B : Liveblocks[K] extends B ? Liveblocks[K] : ErrorType;
1009
- declare type DP = GetOverride<"Presence", JsonObject, "is not a valid JSON object">;
1010
- declare type DS = GetOverride<"Storage", LsonObject, "is not a valid LSON value">;
1011
- declare type DU = GetOverrideOrErrorValue<"UserMeta", BaseUserMeta, Record<"id" | "info", MakeErrorString<"UserMeta">>>;
1012
- declare type DE = GetOverride<"RoomEvent", Json, "is not a valid JSON value">;
1013
- declare type DM = GetOverride<"ThreadMetadata", BaseMetadata>;
1014
- declare type DRI = GetOverride<"RoomInfo", BaseRoomInfo>;
1015
- declare type DAD = GetOverrideOrErrorValue<"ActivitiesData", BaseActivitiesData, {
1016
- [K in keyof Liveblocks["ActivitiesData"]]: "At least one of the custom notification kinds you provided for 'ActivitiesData' does not match its requirements. To learn how to fix this, see https://liveblocks.io/docs/errors/ActivitiesData";
1017
- }>;
1018
- declare type KDAD = keyof DAD extends `$${string}` ? keyof DAD : "Custom notification kinds must start with '$' but your custom 'ActivitiesData' type contains at least one kind which doesn't. To learn how to fix this, see https://liveblocks.io/docs/errors/ActivitiesData";
1019
1076
 
1020
1077
  /**
1021
- * Use this symbol to brand an object property as internal.
1078
+ * Returns a human-readable status indicating the current connection status of
1079
+ * a Room, as returned by `room.getStatus()`. Can be used to implement
1080
+ * a connection status badge.
1081
+ */
1082
+ declare type Status = "initial" | "connecting" | "connected" | "reconnecting" | "disconnected";
1083
+ /**
1084
+ * Used to report about app-level reconnection issues.
1022
1085
  *
1023
- * @example
1024
- * Object.defineProperty(
1025
- * {
1026
- * public,
1027
- * [kInternal]: {
1028
- * private
1029
- * },
1030
- * },
1031
- * kInternal,
1032
- * {
1033
- * enumerable: false,
1034
- * }
1035
- * );
1086
+ * Normal (quick) reconnects won't be reported as a "lost connection". Instead,
1087
+ * the application will only get an event if the reconnection attempts by the
1088
+ * client are taking (much) longer than usual. Definitely a situation you want
1089
+ * to inform your users about, for example, by throwing a toast message on
1090
+ * screen, or show a "trying to reconnect" banner.
1036
1091
  */
1037
- declare const kInternal: unique symbol;
1038
-
1039
- declare type RenameDataField<T, TFieldName extends string> = T extends any ? {
1040
- [K in keyof T as K extends "data" ? TFieldName : K]: T[K];
1041
- } : never;
1042
- declare type AsyncLoading<F extends string = "data"> = RenameDataField<{
1043
- readonly isLoading: true;
1044
- readonly data?: never;
1045
- readonly error?: never;
1046
- }, F>;
1047
- declare type AsyncSuccess<T, F extends string = "data"> = RenameDataField<{
1048
- readonly isLoading: false;
1049
- readonly data: T;
1050
- readonly error?: never;
1051
- }, F>;
1052
- declare type AsyncError<F extends string = "data"> = RenameDataField<{
1053
- readonly isLoading: false;
1054
- readonly data?: never;
1055
- readonly error: Error;
1056
- }, F>;
1057
- declare type AsyncResult<T, F extends string = "data"> = AsyncLoading<F> | AsyncSuccess<T, F> | AsyncError<F>;
1058
-
1059
- declare type BatchStore<O, I> = Observable<void> & {
1060
- get: (input: I) => Promise<void>;
1061
- getState: (input: I) => AsyncResult<O> | undefined;
1092
+ declare type LostConnectionEvent = "lost" | "restored" | "failed";
1093
+ /**
1094
+ * Arbitrary record that will be used as the authentication "authValue". It's the
1095
+ * value that is returned by calling the authentication delegate, and will get
1096
+ * passed to the connection factory delegate. This value will be remembered by
1097
+ * the connection manager, but its value will not be interpreted, so it can be
1098
+ * any value (except null).
1099
+ */
1100
+ declare type BaseAuthResult = NonNullable<Json>;
1101
+ declare class LiveblocksError extends Error {
1102
+ code: number;
1103
+ }
1104
+ declare type Delegates<T extends BaseAuthResult> = {
1105
+ authenticate: () => Promise<T>;
1106
+ createSocket: (authValue: T) => IWebSocketInstance;
1107
+ canZombie: () => boolean;
1062
1108
  };
1063
1109
 
1064
1110
  declare enum ClientMsgCode {
@@ -1442,32 +1488,6 @@ declare namespace DevToolsTreeNode {
1442
1488
  export type { DevToolsTreeNode_CustomEventTreeNode as CustomEventTreeNode, DevToolsTreeNode_JsonTreeNode as JsonTreeNode, DevToolsTreeNode_LiveTreeNode as LiveTreeNode, DevToolsTreeNode_LsonTreeNode as LsonTreeNode, DevToolsTreeNode_TreeNode as TreeNode, DevToolsTreeNode_UserTreeNode as UserTreeNode };
1443
1489
  }
1444
1490
 
1445
- /**
1446
- * This helper type is effectively a no-op, but will force TypeScript to
1447
- * "evaluate" any named helper types in its definition. This can sometimes make
1448
- * API signatures clearer in IDEs.
1449
- *
1450
- * For example, in:
1451
- *
1452
- * type Payload<T> = { data: T };
1453
- *
1454
- * let r1: Payload<string>;
1455
- * let r2: Resolve<Payload<string>>;
1456
- *
1457
- * The inferred type of `r1` is going to be `Payload<string>` which shows up in
1458
- * editor hints, and it may be unclear what's inside if you don't know the
1459
- * definition of `Payload`.
1460
- *
1461
- * The inferred type of `r2` is going to be `{ data: string }`, which may be
1462
- * more helpful.
1463
- *
1464
- * This trick comes from:
1465
- * https://effectivetypescript.com/2022/02/25/gentips-4-display/
1466
- */
1467
- declare type Resolve<T> = T extends (...args: unknown[]) => unknown ? T : {
1468
- [K in keyof T]: T[K];
1469
- };
1470
-
1471
1491
  /**
1472
1492
  * Represents a user connected in a room. Treated as immutable.
1473
1493
  */
@@ -1784,11 +1804,15 @@ declare type SubscribeFn<P extends JsonObject, _TStorage extends LsonObject, U e
1784
1804
  (type: "comments", listener: Callback<CommentsEventServerMsg>): () => void;
1785
1805
  };
1786
1806
  declare type GetThreadsOptions<M extends BaseMetadata> = {
1807
+ cursor?: string;
1787
1808
  query?: {
1788
1809
  resolved?: boolean;
1789
1810
  metadata?: Partial<QueryMetadata<M>>;
1790
1811
  };
1791
1812
  };
1813
+ declare type GetThreadsSinceOptions = {
1814
+ since: Date;
1815
+ };
1792
1816
  declare type UploadAttachmentOptions = {
1793
1817
  signal?: AbortSignal;
1794
1818
  };
@@ -2015,6 +2039,7 @@ declare type Room<P extends JsonObject = DP, S extends LsonObject = DS, U extend
2015
2039
  threads: ThreadData<M>[];
2016
2040
  inboxNotifications: InboxNotificationData[];
2017
2041
  requestedAt: Date;
2042
+ nextCursor: string | null;
2018
2043
  }>;
2019
2044
  /**
2020
2045
  * Returns the updated and deleted threads and their associated inbox notifications since the requested date.
@@ -2024,9 +2049,7 @@ declare type Room<P extends JsonObject = DP, S extends LsonObject = DS, U extend
2024
2049
  * // ... //
2025
2050
  * await room.getThreadsSince({ since: result.requestedAt });
2026
2051
  */
2027
- getThreadsSince(options: {
2028
- since: Date;
2029
- }): Promise<{
2052
+ getThreadsSince(options: GetThreadsSinceOptions): Promise<{
2030
2053
  threads: {
2031
2054
  updated: ThreadData<M>[];
2032
2055
  deleted: ThreadDeleteInfo[];
@@ -2284,26 +2307,6 @@ declare class CommentsApiError extends Error {
2284
2307
  constructor(message: string, status: number, details?: JsonObject | undefined);
2285
2308
  }
2286
2309
 
2287
- /**
2288
- * A Store is just a mini Zustand store.
2289
- */
2290
- declare type Store<T> = {
2291
- get: () => Readonly<T>;
2292
- set: (callback: (currentState: Readonly<T>) => Readonly<T>) => void;
2293
- subscribe: (callback: () => void) => () => void;
2294
- batch: (callback: () => void) => void;
2295
- };
2296
- /**
2297
- * Create a store for an immutable state. Close to Zustand's vanilla store conceptually but with less features.
2298
- */
2299
- declare function createStore<T>(initialState: T): Store<T>;
2300
-
2301
- /**
2302
- * Back-port of TypeScript 5.4's built-in NoInfer utility type.
2303
- * See https://stackoverflow.com/a/56688073/148872
2304
- */
2305
- declare type NoInfr<A> = [A][A extends any ? 0 : never];
2306
-
2307
2310
  declare type OptionalPromise<T> = T | Promise<T>;
2308
2311
 
2309
2312
  declare type ResolveMentionSuggestionsArgs = {
@@ -2371,12 +2374,13 @@ declare type PrivateClientApi<U extends BaseUserMeta, M extends BaseMetadata> =
2371
2374
  readonly usersStore: BatchStore<U["info"] | undefined, string>;
2372
2375
  readonly roomsInfoStore: BatchStore<DRI | undefined, string>;
2373
2376
  readonly getRoomIds: () => string[];
2374
- readonly getThreads: (options: GetThreadsOptions<M>) => Promise<{
2377
+ readonly getUserThreads_experimental: (options: GetThreadsOptions<M>) => Promise<{
2375
2378
  threads: ThreadData<M>[];
2376
2379
  inboxNotifications: InboxNotificationData[];
2380
+ nextCursor: string | null;
2377
2381
  requestedAt: Date;
2378
2382
  }>;
2379
- readonly getThreadsSince: (options: {
2383
+ readonly getUserThreadsSince_experimental: (options: {
2380
2384
  since: Date;
2381
2385
  } & GetThreadsOptions<M>) => Promise<{
2382
2386
  inboxNotifications: {
@@ -2392,32 +2396,50 @@ declare type PrivateClientApi<U extends BaseUserMeta, M extends BaseMetadata> =
2392
2396
  };
2393
2397
  declare type NotificationsApi<M extends BaseMetadata> = {
2394
2398
  /**
2395
- * Gets the current user inbox notifications and their associated threads.
2396
- * It also returns the request date that can be used for subsequent polling.
2399
+ * Gets a page (or the initial page) for user inbox notifications and their
2400
+ * associated threads.
2401
+ *
2402
+ * This function should NOT be used for delta updates, only for pagination
2403
+ * (including the first page fetch). For delta updates (done during the
2404
+ * periodic polling), use the `getInboxNotificationsSince` function.
2397
2405
  *
2398
2406
  * @example
2399
2407
  * const {
2400
2408
  * inboxNotifications,
2401
2409
  * threads,
2402
- * requestedAt
2410
+ * nextCursor,
2403
2411
  * } = await client.getInboxNotifications();
2412
+ * const data = await client.getInboxNotifications(); // Fetch initial page (of 20 inbox notifications)
2413
+ * const data = await client.getInboxNotifications({ cursor: nextCursor }); // Fetch next page (= next 20 inbox notifications)
2404
2414
  */
2405
- getInboxNotifications(): Promise<{
2415
+ getInboxNotifications(options?: {
2416
+ cursor?: string;
2417
+ }): Promise<{
2406
2418
  inboxNotifications: InboxNotificationData[];
2407
2419
  threads: ThreadData<M>[];
2420
+ nextCursor: string | null;
2408
2421
  requestedAt: Date;
2409
2422
  }>;
2410
2423
  /**
2411
- * Gets the updated and deleted inbox notifications and their associated threads since the requested date.
2424
+ * Fetches a "delta update" since the last time we updated.
2425
+ *
2426
+ * This function should NOT be used for pagination, for that, see the
2427
+ * `getInboxNotifications` function.
2412
2428
  *
2413
2429
  * @example
2414
- * const result = await client.getInboxNotifications();
2415
- * // ... //
2416
- * await client.getInboxNotificationsSince({ since: result.requestedAt }});
2417
- */
2418
- getInboxNotificationsSince(options: {
2419
- since: Date;
2420
- }): Promise<{
2430
+ * const {
2431
+ * inboxNotifications: {
2432
+ * updated,
2433
+ * deleted,
2434
+ * },
2435
+ * threads: {
2436
+ * updated,
2437
+ * deleted,
2438
+ * },
2439
+ * requestedAt,
2440
+ * } = await client.getInboxNotificationsSince({ since: result.requestedAt }});
2441
+ */
2442
+ getInboxNotificationsSince(since: Date): Promise<{
2421
2443
  inboxNotifications: {
2422
2444
  updated: InboxNotificationData[];
2423
2445
  deleted: InboxNotificationDeleteInfo[];
@@ -2759,6 +2781,9 @@ declare function nn<T>(value: T, errmsg?: string): NonNullable<T>;
2759
2781
  * @param throwError An optional function to not auto-retry on certain errors
2760
2782
  */
2761
2783
  declare function autoRetry<T>(promiseFn: () => Promise<T>, maxTries: number, backoff: number[], throwError?: (err: any) => boolean): Promise<T>;
2784
+ declare class StopRetrying extends Error {
2785
+ constructor(reason: string);
2786
+ }
2762
2787
 
2763
2788
  declare function chunk<T>(array: T[], size: number): T[][];
2764
2789
 
@@ -2847,13 +2872,14 @@ declare function objectToQuery(obj: {
2847
2872
  }): string;
2848
2873
 
2849
2874
  declare type Poller = {
2850
- start(interval: number): void;
2851
- restart(interval: number): void;
2852
- pause(): void;
2853
- resume(): void;
2854
- stop(): void;
2875
+ /**
2876
+ * Starts or stops the poller, based on the given condition. When true,
2877
+ * starts the poller if it hasn't been started already. When false, stops the
2878
+ * poller if it hasn't been stopped already.
2879
+ */
2880
+ enable(condition: boolean): void;
2855
2881
  };
2856
- declare function makePoller(callback: () => Promise<void> | void): Poller;
2882
+ declare function makePoller(callback: () => Promise<void> | void, interval: number): Poller;
2857
2883
 
2858
2884
  declare const brand: unique symbol;
2859
2885
  declare type Brand<T, TBrand extends string> = T & {
@@ -2986,6 +3012,10 @@ declare function asPos(str: string): Pos;
2986
3012
  declare function shallow(a: unknown, b: unknown): boolean;
2987
3013
 
2988
3014
  declare type OmitFirstTupleElement<T extends any[]> = T extends [any, ...infer R] ? R : never;
3015
+ /**
3016
+ * Like JSON.stringify(), but returns the same value no matter how the keys in
3017
+ * objects are ordered.
3018
+ */
2989
3019
  declare function stringify(object: Parameters<typeof JSON.stringify>[0], ...args: OmitFirstTupleElement<Parameters<typeof JSON.stringify>>): string;
2990
3020
 
2991
3021
  declare type QueryParams = Record<string, string | number | null | undefined> | URLSearchParams;
@@ -3146,4 +3176,4 @@ declare type EnsureJson<T> = T extends Json ? T : T extends Array<infer I> ? (En
3146
3176
  [K in keyof T as EnsureJson<T[K]> extends never ? never : K]: EnsureJson<T[K]>;
3147
3177
  };
3148
3178
 
3149
- export { type AckOp, type ActivityData, type AsyncError, type AsyncLoading, type AsyncResult, type AsyncSuccess, type BaseActivitiesData, type BaseAuthResult, type BaseMetadata, type BaseRoomInfo, type BaseUserMeta, type Brand, type BroadcastEventClientMsg, type BroadcastOptions, type BroadcastedEventServerMsg, type Client, type ClientMsg, ClientMsgCode, type ClientOptions, type CommentAttachment, type CommentBody, type CommentBodyBlockElement, type CommentBodyElement, type CommentBodyInlineElement, type CommentBodyLink, type CommentBodyLinkElementArgs, type CommentBodyMention, type CommentBodyMentionElementArgs, type CommentBodyParagraph, type CommentBodyParagraphElementArgs, type CommentBodyText, type CommentBodyTextElementArgs, type CommentData, type CommentDataPlain, type CommentLocalAttachment, type CommentMixedAttachment, type CommentReaction, type CommentUserReaction, type CommentUserReactionPlain, CommentsApiError, type CommentsEventServerMsg, CrdtType, type CreateListOp, type CreateMapOp, type CreateObjectOp, type CreateOp, type CreateRegisterOp, type CustomAuthenticationResult, type DAD, type DE, type DM, type DP, type DRI, type DS, type DU, type Delegates, type DeleteCrdtOp, type DeleteObjectKeyOp, DevToolsTreeNode as DevTools, protocol as DevToolsMsg, type DistributiveOmit, type EnsureJson, type EnterOptions, type EventSource, type FetchStorageClientMsg, type FetchYDocClientMsg, type GetThreadsOptions, type History, type HistoryVersion, type IUserInfo, type IWebSocket, type IWebSocketCloseEvent, type IWebSocketEvent, type IWebSocketInstance, type IWebSocketMessageEvent, type IdTuple, type Immutable, type InboxNotificationCustomData, type InboxNotificationCustomDataPlain, type InboxNotificationData, type InboxNotificationDataPlain, type InboxNotificationDeleteInfo, type InboxNotificationTextMentionData, type InboxNotificationTextMentionDataPlain, type InboxNotificationThreadData, type InboxNotificationThreadDataPlain, type InitialDocumentStateServerMsg, type Json, type JsonArray, type JsonObject, type JsonScalar, type KDAD, LiveList, type LiveListUpdate, LiveMap, type LiveMapUpdate, type LiveNode, LiveObject, type LiveObjectUpdate, type LiveStructure, LiveblocksError, type LostConnectionEvent, type Lson, type LsonObject, type NoInfr, type NodeMap, NotificationsApiError, type Op, OpCode, type OpaqueClient, type OpaqueRoom, type OptionalPromise, type OptionalTupleUnless, type OthersEvent, type ParentToChildNodeMap, type PartialUnless, type Patchable, type PlainLson, type PlainLsonFields, type PlainLsonList, type PlainLsonMap, type PlainLsonObject, type PrivateClientApi, type PrivateRoomApi, type QueryMetadata, type QueryParams, type RejectedStorageOpServerMsg, type Resolve, type ResolveMentionSuggestionsArgs, type ResolveRoomsInfoArgs, type ResolveUsersArgs, type Room, type RoomEventMessage, type RoomNotificationSettings, type RoomStateServerMsg, type SerializedChild, type SerializedCrdt, type SerializedList, type SerializedMap, type SerializedObject, type SerializedRegister, type SerializedRootObject, type ServerMsg, ServerMsgCode, type SetParentKeyOp, type Status, type StorageStatus, type StorageUpdate, type Store, type StringifyCommentBodyElements, type StringifyCommentBodyOptions, type ThreadData, type ThreadDataPlain, type ThreadDataWithDeleteInfo, type ThreadDeleteInfo, type ToImmutable, type ToJson, type URLSafeString, type UnsubscribeCallback, type UpdateObjectOp, type UpdatePresenceClientMsg, type UpdatePresenceServerMsg, type UpdateStorageClientMsg, type UpdateStorageServerMsg, type UpdateYDocClientMsg, type UploadAttachmentOptions, type User, type UserJoinServerMsg, type UserLeftServerMsg, WebsocketCloseCodes, type YDocUpdateServerMsg, ackOp, asPos, assert, assertNever, autoRetry, b64decode, chunk, cloneLson, compactObject, fancyConsole as console, convertToCommentData, convertToCommentUserReaction, convertToInboxNotificationData, convertToThreadData, createClient, createCommentId, createInboxNotificationId, createStore, createThreadId, deprecate, deprecateIf, detectDupes, errorIf, freeze, getMentionedIdsFromCommentBody, isChildCrdt, isJsonArray, isJsonObject, isJsonScalar, isLiveNode, isPlainObject, isRootCrdt, kInternal, legacy_patchImmutableObject, lsonToJson, makeEventSource, makePoller, makePosition, mapValues, memoizeOnSuccess, nanoid, nn, objectToQuery, patchLiveObjectKey, raise, shallow, stringify, stringifyCommentBody, throwUsageError, toPlainLson, tryParseJson, url, urljoin, wait, withTimeout };
3179
+ export { type AckOp, type ActivityData, type AsyncError, type AsyncLoading, type AsyncResult, type AsyncSuccess, type BaseActivitiesData, type BaseAuthResult, type BaseMetadata, type BaseRoomInfo, type BaseUserMeta, type Brand, type BroadcastEventClientMsg, type BroadcastOptions, type BroadcastedEventServerMsg, type Client, type ClientMsg, ClientMsgCode, type ClientOptions, type CommentAttachment, type CommentBody, type CommentBodyBlockElement, type CommentBodyElement, type CommentBodyInlineElement, type CommentBodyLink, type CommentBodyLinkElementArgs, type CommentBodyMention, type CommentBodyMentionElementArgs, type CommentBodyParagraph, type CommentBodyParagraphElementArgs, type CommentBodyText, type CommentBodyTextElementArgs, type CommentData, type CommentDataPlain, type CommentLocalAttachment, type CommentMixedAttachment, type CommentReaction, type CommentUserReaction, type CommentUserReactionPlain, CommentsApiError, type CommentsEventServerMsg, CrdtType, type CreateListOp, type CreateMapOp, type CreateObjectOp, type CreateOp, type CreateRegisterOp, type CustomAuthenticationResult, type DAD, type DE, type DM, type DP, type DRI, type DS, type DU, type Delegates, type DeleteCrdtOp, type DeleteObjectKeyOp, DevToolsTreeNode as DevTools, protocol as DevToolsMsg, type DistributiveOmit, type EnsureJson, type EnterOptions, type EventSource, type FetchStorageClientMsg, type FetchYDocClientMsg, type GetThreadsOptions, type History, type HistoryVersion, type IUserInfo, type IWebSocket, type IWebSocketCloseEvent, type IWebSocketEvent, type IWebSocketInstance, type IWebSocketMessageEvent, type IdTuple, type Immutable, type InboxNotificationCustomData, type InboxNotificationCustomDataPlain, type InboxNotificationData, type InboxNotificationDataPlain, type InboxNotificationDeleteInfo, type InboxNotificationTextMentionData, type InboxNotificationTextMentionDataPlain, type InboxNotificationThreadData, type InboxNotificationThreadDataPlain, type InitialDocumentStateServerMsg, type Json, type JsonArray, type JsonObject, type JsonScalar, type KDAD, LiveList, type LiveListUpdate, LiveMap, type LiveMapUpdate, type LiveNode, LiveObject, type LiveObjectUpdate, type LiveStructure, LiveblocksError, type LostConnectionEvent, type Lson, type LsonObject, type NoInfr, type NodeMap, NotificationsApiError, type Observable, type Op, OpCode, type OpaqueClient, type OpaqueRoom, type OptionalPromise, type OptionalTupleUnless, type OthersEvent, type ParentToChildNodeMap, type PartialUnless, type Patchable, type PlainLson, type PlainLsonFields, type PlainLsonList, type PlainLsonMap, type PlainLsonObject, type PrivateClientApi, type PrivateRoomApi, type QueryMetadata, type QueryParams, type RejectedStorageOpServerMsg, type Resolve, type ResolveMentionSuggestionsArgs, type ResolveRoomsInfoArgs, type ResolveUsersArgs, type Room, type RoomEventMessage, type RoomNotificationSettings, type RoomStateServerMsg, type SerializedChild, type SerializedCrdt, type SerializedList, type SerializedMap, type SerializedObject, type SerializedRegister, type SerializedRootObject, type ServerMsg, ServerMsgCode, type SetParentKeyOp, type Status, StopRetrying, type StorageStatus, type StorageUpdate, type Store, type StringifyCommentBodyElements, type StringifyCommentBodyOptions, type ThreadData, type ThreadDataPlain, type ThreadDataWithDeleteInfo, type ThreadDeleteInfo, type ToImmutable, type ToJson, type URLSafeString, type UnsubscribeCallback, type UpdateObjectOp, type UpdatePresenceClientMsg, type UpdatePresenceServerMsg, type UpdateStorageClientMsg, type UpdateStorageServerMsg, type UpdateYDocClientMsg, type UploadAttachmentOptions, type User, type UserJoinServerMsg, type UserLeftServerMsg, WebsocketCloseCodes, type YDocUpdateServerMsg, ackOp, asPos, assert, assertNever, autoRetry, b64decode, chunk, cloneLson, compactObject, fancyConsole as console, convertToCommentData, convertToCommentUserReaction, convertToInboxNotificationData, convertToThreadData, createClient, createCommentId, createInboxNotificationId, createStore, createThreadId, deprecate, deprecateIf, detectDupes, errorIf, freeze, getMentionedIdsFromCommentBody, isChildCrdt, isJsonArray, isJsonObject, isJsonScalar, isLiveNode, isPlainObject, isRootCrdt, kInternal, legacy_patchImmutableObject, lsonToJson, makeEventSource, makePoller, makePosition, mapValues, memoizeOnSuccess, nanoid, nn, objectToQuery, patchLiveObjectKey, raise, shallow, stringify, stringifyCommentBody, throwUsageError, toPlainLson, tryParseJson, url, urljoin, wait, withTimeout };