@pluv/client 2.0.2 → 2.2.0

package/src/PluvRoom.ts

@@ -1,16 +1,19 @@
 import type {
     AbstractCrdtDocFactory,
-    CrdtType,
     InferCrdtJson,
+    InferDoc,
+    InferDocLike,
     InferStorage,
     NoopCrdtDocFactory,
 } from "@pluv/crdt";
 import type {
     BaseIOEventRecord,
     BaseUser,
+    BroadcastProxy,
     CrdtDocLike,
     EventMessage,
     EventNotifierSubscriptionCallback,
+    EventProxy,
     IOEventMessage,
     IOLike,
     Id,
@@ -22,23 +25,31 @@ import type {
     JsonObject,
     MergeEvents,
     OptionalProps,
-    OtherNotifierSubscriptionCallback,
+    OtherSubscriptionCallback,
+    OthersSubscriptionCallback,
+    RoomEventListenerMap,
     RoomLike,
+    StateNotifierSubjects,
+    StorageProxy,
+    StorageRootSubscriptionCallback,
+    StorageSubscriptionCallback,
+    SubscribeProxy,
+    SubscriptionCallback,
     UpdateMyPresenceAction,
     UserInfo,
+    WebSocketConnection,
     WebSocketState,
 } from "@pluv/types";
-import { ConnectionState } from "@pluv/types";
+import { ConnectionState, StorageState } from "@pluv/types";
 import type { AbstractStorageStore } from "./AbstractStorageStore";
 import type { CrdtManagerOptions } from "./CrdtManager";
 import { CrdtManager } from "./CrdtManager";
 import { CrdtNotifier } from "./CrdtNotifier";
 import { EventNotifier } from "./EventNotifier";
-import { OtherNotifier } from "./OtherNotifier";
+import { ListenerManager } from "./ListenerManager";
 import { PluvProcedure } from "./PluvProcedure";
 import type { PluvRouterEventConfig } from "./PluvRouter";
 import { PluvRouter } from "./PluvRouter";
-import type { StateNotifierSubjects, SubscriptionCallback } from "./StateNotifier";
 import { StateNotifier } from "./StateNotifier";
 import { StorageStore } from "./StorageStore";
 import type {
@@ -48,11 +59,11 @@ import type {
     InternalSubscriptions,
     PluvClientLimits,
     PublicKey,
-    WebSocketConnection,
     WithMetadata,
 } from "./types";
 import type { UsersManagerConfig } from "./UsersManager";
 import { UsersManager } from "./UsersManager";
+import { UsersNotifier } from "./UsersNotifier";
 import { debounce } from "./utils";
 
 const ADD_TO_STORAGE_STATE_DEBOUNCE_MS = 1_000;
@@ -78,8 +89,8 @@ declare global {
 export const DEFAULT_PLUV_CLIENT_ADDON = <
     TIO extends IOLike,
     TMetadata extends JsonObject,
-    TPresence extends JsonObject,
-    TCrdt extends AbstractCrdtDocFactory<any>,
+    TPresence extends Record<string, any>,
+    TCrdt extends AbstractCrdtDocFactory<any, any>,
 >(
     input: PluvRoomAddonInput<TIO, TMetadata, TPresence, TCrdt>,
 ): PluvRoomAddonResult => ({
@@ -95,9 +106,9 @@ interface WindowListeners {
 
 interface WebSocketListeners {
     onClose: (event: CloseEvent) => void;
-    onError: () => void;
+    onError: (event: Event) => void;
     onMessage: (message: MessageEvent<string>) => void;
-    onOpen: () => void;
+    onOpen: (event: Event) => void;
 }
 
 interface IntervalIds {
@@ -136,15 +147,15 @@ interface InternalListeners {
 export type PluvRoomAddon<
     TIO extends IOLike,
     TMetadata extends JsonObject,
-    TPresence extends JsonObject,
-    TCrdt extends AbstractCrdtDocFactory<any>,
+    TPresence extends Record<string, any>,
+    TCrdt extends AbstractCrdtDocFactory<any, any>,
 > = (input: PluvRoomAddonInput<TIO, TMetadata, TPresence, TCrdt>) => Partial<PluvRoomAddonResult>;
 
 export interface PluvRoomAddonInput<
     TIO extends IOLike,
     TMetadata extends JsonObject,
-    TPresence extends JsonObject,
-    TCrdt extends AbstractCrdtDocFactory<any>,
+    TPresence extends Record<string, any>,
+    TCrdt extends AbstractCrdtDocFactory<any, any>,
 > {
     room: PluvRoom<TIO, TMetadata, TPresence, TCrdt>;
 }
@@ -174,8 +185,8 @@ export type ReconnectTimeoutMs = number | ((params: ReconnectTimeoutMsParams) =>
 export type RoomConfig<
     TIO extends IOLike,
     TMetadata extends JsonObject,
-    TPresence extends JsonObject,
-    TCrdt extends AbstractCrdtDocFactory<any>,
+    TPresence extends Record<string, any>,
+    TCrdt extends AbstractCrdtDocFactory<any, any>,
     TEvents extends PluvRouterEventConfig<TIO, TPresence, InferStorage<TCrdt>>,
 > = Id<
     {
@@ -195,10 +206,10 @@ export type RoomConfig<
 export class PluvRoom<
     TIO extends IOLike<any, any>,
     TMetadata extends JsonObject = {},
-    TPresence extends JsonObject = {},
-    TCrdt extends AbstractCrdtDocFactory<any> = NoopCrdtDocFactory,
+    TPresence extends Record<string, any> = {},
+    TCrdt extends AbstractCrdtDocFactory<any, any> = NoopCrdtDocFactory,
     TEvents extends PluvRouterEventConfig<TIO, TPresence, InferStorage<TCrdt>> = {},
-> implements RoomLike<TIO, TPresence, InferStorage<TCrdt>>
+> implements RoomLike<TIO, InferDoc<TCrdt>, TPresence, InferStorage<TCrdt>>
 {
     readonly _endpoints: RoomEndpoints<TIO, TMetadata>;
 
@@ -213,8 +224,8 @@ export class PluvRoom<
         heartbeat: null,
     };
     private readonly _limits: PluvClientLimits;
+    private readonly _listenerManager = new ListenerManager();
     private readonly _listeners: InternalListeners;
-    private readonly _otherNotifier = new OtherNotifier<TIO, TPresence>();
     private readonly _publicKey: PublicKey<TMetadata> | null = null;
     private readonly _reconnectTimeoutMs: ReconnectTimeoutMs;
     private readonly _router: PluvRouter<TIO, TPresence, InferStorage<TCrdt>, TEvents>;
@@ -228,6 +239,7 @@ export class PluvRoom<
         reconnect: null,
     };
     private readonly _usersManager: UsersManager<TIO, TPresence>;
+    private readonly _usersNotifier = new UsersNotifier<TIO, TPresence>();
 
     private _lastMetadata: TMetadata | null = null;
     private _state: WebSocketState<TIO> = {
@@ -237,10 +249,12 @@ export class PluvRoom<
         },
         connection: {
             attempts: 0,
-            count: 0,
             id: null,
             state: ConnectionState.Untouched,
         },
+        storage: {
+            state: StorageState.Unavailable,
+        },
         webSocket: null,
     };
     private _windowListeners: WindowListeners | null = null;
@@ -297,14 +311,24 @@ export class PluvRoom<
         this._crdtManager = new CrdtManager<TCrdt>({ initialStorage });
     }
 
+    /**
+     * @deprecated To be removed in v3. Use `getStorageLoaded` instead.
+     */
     public get storageLoaded(): boolean {
-        return this._crdtManager.initialized;
+        return this.getStorageLoaded();
     }
 
     public get webSocket(): WebSocket | null {
         return this._state.webSocket;
     }
 
+    public addEventListener<TKind extends keyof RoomEventListenerMap>(
+        kind: TKind,
+        handler: RoomEventListenerMap[TKind],
+    ): () => void {
+        return this._listenerManager.subscribe(kind, handler as any);
+    }
+
     public broadcast = new Proxy(
         async <TEvent extends keyof InferIOInput<MergeEvents<TEvents, TIO>>>(
             event: TEvent,
@@ -320,7 +344,8 @@ export class PluvRoom<
                 any,
                 any,
                 TPresence,
-                InferStorage<TCrdt>
+                TCrdt,
+                ""
             > | null;
 
             if (!procedure?.config.broadcast) {
@@ -334,7 +359,7 @@ export class PluvRoom<
             if (!myself) return;
 
             const parsed = procedure.config.input ? procedure.config.input.parse(data) : data;
-            const context: EventResolverContext<TIO, TPresence, InferStorage<TCrdt>> = {
+            const context: EventResolverContext<TIO, TPresence, InferDocLike<TCrdt>> = {
                 doc: this._crdtManager.doc,
                 others: this._usersManager.getOthers(),
                 room: this.id,
@@ -364,14 +389,7 @@ export class PluvRoom<
                 };
             },
         },
-    ) as (<TEvent extends keyof InferIOInput<MergeEvents<TEvents, TIO>>>(
-        event: TEvent,
-        data: Id<InferIOInput<MergeEvents<TEvents, TIO>>[TEvent]>,
-    ) => Promise<void>) & {
-        [PEvent in keyof InferIOInput<MergeEvents<TEvents, TIO>>]: (
-            data: Id<InferIOInput<MergeEvents<TEvents, TIO>>[PEvent]>,
-        ) => Promise<void>;
-    };
+    ) as BroadcastProxy<TIO, TEvents>;
 
     public canRedo = (): boolean => {
         return !!this._crdtManager.doc.canRedo();
@@ -436,6 +454,7 @@ export class PluvRoom<
         this._updateState((oldState) => {
             oldState.connection.attempts = 0;
             oldState.authorization.token = authToken;
+            oldState.storage.state = StorageState.Loading;
             oldState.webSocket = webSocket;
 
             return oldState;
@@ -460,6 +479,10 @@ export class PluvRoom<
         this._updateState((oldState) => {
             oldState.authorization.token = null;
             oldState.connection.state = ConnectionState.Closed;
+            oldState.storage.state =
+                oldState.storage.state === StorageState.Synced
+                    ? StorageState.Offline
+                    : StorageState.Unavailable;
             oldState.webSocket = null;
 
             return oldState;
@@ -470,6 +493,9 @@ export class PluvRoom<
         this._stateNotifier.subjects["my-presence"].next(null);
     }
 
+    /**
+     * @deprecated To be removed in v3. Use PluvRoom.subscribe.event instead
+     */
     public event = new Proxy(
         <TEvent extends keyof InferIOOutput<MergeEvents<TEvents, TIO>>>(
             event: TEvent,
@@ -482,21 +508,14 @@ export class PluvRoom<
                 ): (() => void) => fn(prop as any, callback);
             },
         },
-    ) as (<TEvent extends keyof InferIOOutput<MergeEvents<TEvents, TIO>>>(
-        event: TEvent,
-        callback: EventNotifierSubscriptionCallback<MergeEvents<TEvents, TIO>, TEvent>,
-    ) => () => void) & {
-        [PEvent in keyof InferIOOutput<MergeEvents<TEvents, TIO>>]: (
-            callback: EventNotifierSubscriptionCallback<MergeEvents<TEvents, TIO>, PEvent>,
-        ) => () => void;
-    };
+    ) as EventProxy<TIO, TEvents>;
 
     public getConnection = (): WebSocketConnection => {
         // Create a read-only clone of the connection state
         return Object.freeze(JSON.parse(JSON.stringify(this._state.connection)));
     };
 
-    public getDoc = (): CrdtDocLike<InferStorage<TCrdt>> => {
+    public getDoc = (): CrdtDocLike<InferDoc<TCrdt>, InferStorage<TCrdt>> => {
         return this._crdtManager.doc;
     };
 
@@ -532,7 +551,6 @@ export class PluvRoom<
     ): InferCrdtJson<InferStorage<TCrdt>[TKey]> | null;
     public getStorageJson<TKey extends keyof InferStorage<TCrdt>>(type?: TKey) {
         if (this._state.connection.id === null) return null;
-
         if (typeof type === "undefined") return this._crdtManager.doc.toJson();
 
         const sharedType = this._crdtManager.get(type);
@@ -542,42 +560,111 @@ export class PluvRoom<
         return this._crdtManager.doc.toJson(type);
     }
 
+    public getStorageLoaded = (): boolean => {
+        return (
+            this._state.storage.state === StorageState.Offline ||
+            this._state.storage.state === StorageState.Synced
+        );
+    };
+
+    /**
+     * @deprecated To be removed in v3. Use PluvRoom.subscribe.other instead
+     */
     public other = (
         connectionId: string,
-        callback: OtherNotifierSubscriptionCallback<TIO, TPresence>,
+        callback: OtherSubscriptionCallback<TIO, TPresence>,
     ): (() => void) => {
         const clientId = this._usersManager.getClientId(connectionId);
 
         if (!clientId) return () => undefined;
 
-        return this._otherNotifier.subscribe(clientId, callback);
+        return this._usersNotifier.subscribeOther(clientId, callback);
     };
 
     public redo = (): void => {
         this._crdtManager.doc.redo();
     };
 
-    public storage = <TKey extends keyof InferStorage<TCrdt>>(
-        key: TKey,
-        fn: (value: InferCrdtJson<InferStorage<TCrdt>[TKey]>) => void,
-    ): (() => void) => {
-        return this._crdtNotifier.subscribe(key, fn);
-    };
+    /**
+     * @deprecated To be removed in v3. Use PluvRoom.subscribe.storage instead
+     */
+    public storage = new Proxy(
+        <TKey extends keyof InferStorage<TCrdt>>(
+            key: TKey,
+            callback: StorageSubscriptionCallback<InferStorage<TCrdt>, TKey>,
+        ): (() => void) => this._crdtNotifier.subscribe(key, callback),
+        {
+            get: (fn, prop) => {
+                type _Storage = InferStorage<TCrdt>;
+
+                if (!!prop) {
+                    return (callback: StorageRootSubscriptionCallback<_Storage>) => {
+                        return this._crdtNotifier.subcribeRoot(callback);
+                    };
+                }
+
+                return (callback: StorageSubscriptionCallback<_Storage, keyof _Storage>) => {
+                    return fn(prop as keyof InferStorage<TCrdt>, callback);
+                };
+            },
+        },
+    ) as StorageProxy<InferStorage<TCrdt>>;
 
+    /**
+     * @deprecated To be removed in v3. Use PluvRoom.subscribe.storage instead
+     * @description Subscribes to the root storage object (serialized)
+     */
     public storageRoot = (
-        fn: (value: {
+        callback: (value: {
             [P in keyof InferStorage<TCrdt>]: InferCrdtJson<InferStorage<TCrdt>[P]>;
         }) => void,
     ): (() => void) => {
-        return this._crdtNotifier.subcribeRoot(fn);
+        return this._crdtNotifier.subcribeRoot(callback);
     };
 
-    public subscribe = <TSubject extends keyof StateNotifierSubjects<TIO, TPresence>>(
-        name: TSubject,
-        callback: SubscriptionCallback<TIO, TPresence, TSubject>,
-    ): (() => void) => {
-        return this._stateNotifier.subscribe(name, callback);
-    };
+    public subscribe = new Proxy(
+        <TSubject extends keyof StateNotifierSubjects<TIO, TPresence>>(
+            name: TSubject,
+            callback: SubscriptionCallback<TIO, TPresence, TSubject>,
+        ): (() => void) => this._stateNotifier.subscribe(name, callback),
+        {
+            get: (fn, prop) => {
+                if (prop === "connection") {
+                    return (callback: SubscriptionCallback<TIO, TPresence, "connection">) => {
+                        return fn("connection", callback);
+                    };
+                }
+
+                if (prop === "myPresence") {
+                    return (callback: SubscriptionCallback<TIO, TPresence, "my-presence">) => {
+                        return fn("my-presence", callback);
+                    };
+                }
+
+                if (prop === "myself") {
+                    return (callback: SubscriptionCallback<TIO, TPresence, "myself">) => {
+                        return fn("myself", callback);
+                    };
+                }
+
+                if (prop === "others") {
+                    return (callback: OthersSubscriptionCallback<TIO, TPresence>) => {
+                        return this._usersNotifier.subscribeOthers(callback);
+                    };
+                }
+
+                if (prop === "storageLoaded") {
+                    return (callback: SubscriptionCallback<TIO, TPresence, "storage-loaded">) => {
+                        return fn("storage-loaded", callback);
+                    };
+                }
+
+                if (prop === "event") return this.event;
+                if (prop === "other") return this.other;
+                if (prop === "storage") return this.storage;
+            },
+        },
+    ) as SubscribeProxy<TIO, TPresence, InferStorage<TCrdt>, TEvents>;
 
     public transact = (fn: (storage: InferStorage<TCrdt>) => void, origin?: string): void => {
         const _origin = origin ?? this._state.connection.id;
@@ -679,9 +766,10 @@ export class PluvRoom<
         this._detachWindowListeners();
         this._usersManager.removeMyself();
         this._usersManager.clearConnections();
-        this._otherNotifier.clear();
+        this._usersNotifier.clear();
         this._stateNotifier.subjects.myself.next(null);
         this._stateNotifier.subjects.others.next([]);
+        this._usersNotifier.others.next({ others: [], event: { kind: "clear" } });
         this._state.webSocket?.close();
 
         this._detachWsListeners();
@@ -841,13 +929,26 @@ export class PluvRoom<
 
         this._stateNotifier.subjects.others.next(others);
 
+        // Should not reach here
+        if (!deleted) {
+            console.warn("Could not identify exited connection");
+            return;
+        }
+
+        const { data: user, remaining } = deleted;
+
+        this._usersNotifier.others.next({
+            others,
+            event: { kind: "leave", user },
+        });
+
         /**
-         * @description A single user can have multiple connections. So we're checking that there
-         * isn't a remaining connection before choosing to delete that user for other connected
-         * participants.
+         * @description A single user can have multiple connections. So we're checking that
+         * there isn't a remaining connection before choosing to delete that user for other
+         * connected participants.
          * @date April 16, 2025
          */
-        if (!deleted?.remaining && !!clientId) this._otherNotifier.delete(clientId);
+        if (!remaining && !!clientId) this._usersNotifier.delete(clientId);
     }
 
     private _handlePresenceUpdatedMessage(message: IOEventMessage<TIO>): void {
@@ -886,27 +987,41 @@ export class PluvRoom<
 
         if (!!clientId) {
             const other = this._usersManager.getOther(connectionId);
+            const others = this._usersManager.getOthers();
 
-            this._otherNotifier.subject(clientId).next(other);
-        } else {
-            /**
-             * !HACK
-             * @description User could not be found. Add the connection to keep others up-to-date
-             * @date April 19, 2025
-             */
-            const added = this._usersManager.addConnection({
-                connectionId,
-                presence: data.presence as TPresence,
-                user: message.user as Id<InferIOAuthorizeUser<InferIOAuthorize<TIO>>>,
-            });
-            const other = this._usersManager.getOther(connectionId);
+            this._usersNotifier.other(clientId).next(other);
+            this._stateNotifier.subjects.others.next(others);
 
-            this._otherNotifier.subject(added.clientId).next(other);
+            if (!!other) {
+                this._usersNotifier.others.next({
+                    others,
+                    event: { kind: "update", user: other },
+                });
+            }
+
+            return;
         }
 
+        /**
+         * !HACK
+         * @description User could not be found. Add the connection to keep others up-to-date
+         * @date April 19, 2025
+         */
+        const added = this._usersManager.addConnection({
+            connectionId,
+            presence: data.presence as TPresence,
+            user: message.user as Id<InferIOAuthorizeUser<InferIOAuthorize<TIO>>>,
+        });
+        const other = this._usersManager.getOther(connectionId);
         const others = this._usersManager.getOthers();
 
+        this._usersNotifier.other(added.clientId).next(other);
         this._stateNotifier.subjects.others.next(others);
+
+        this._usersNotifier.others.next({
+            others,
+            event: { kind: "update", user: added.data },
+        });
     }
 
     private _handleReceiveOthers(message: IOEventMessage<TIO>): void {
@@ -931,12 +1046,16 @@ export class PluvRoom<
             const clientId = result.clientId;
             const other = this._usersManager.getOther(connectionId);
 
-            this._otherNotifier.subject(clientId).next(other);
+            this._usersNotifier.other(clientId).next(other);
         });
 
         const others = this._usersManager.getOthers();
 
         this._stateNotifier.subjects.others.next(others);
+        this._usersNotifier.others.next({
+            others,
+            event: { kind: "sync", users: others },
+        });
     }
 
     private async _handleRegisteredMessage(message: IOEventMessage<TIO>): Promise<void> {
@@ -951,7 +1070,6 @@ export class PluvRoom<
         const state = data.state;
 
         this._updateState((oldState) => {
-            oldState.connection.count += 1;
             oldState.connection.id = connectionId;
             oldState.authorization.user = user ?? null;
 
@@ -1024,6 +1142,11 @@ export class PluvRoom<
 
         this._emitSharedTypes();
         this._observeCrdt();
+        this._updateState((oldState) => {
+            oldState.storage.state = StorageState.Synced;
+
+            return oldState;
+        });
         this._stateNotifier.subjects["storage-loaded"].next(true);
 
         this._sendMessage({
@@ -1083,6 +1206,13 @@ export class PluvRoom<
 
         quitters.forEach((quitter) => {
             this._usersManager.deleteConnection(quitter.connectionId);
+
+            const remaining = this._usersManager.getOthers();
+
+            this._usersNotifier.others.next({
+                others: remaining,
+                event: { kind: "leave", user: quitter },
+            });
         });
 
         const remaining = this._usersManager.getOthers();
@@ -1115,8 +1245,13 @@ export class PluvRoom<
         const other = this._usersManager.getOther(connectionId);
         const others = this._usersManager.getOthers();
 
-        this._otherNotifier.subject(added.clientId).next(other);
+        this._usersNotifier.other(added.clientId).next(other);
         this._stateNotifier.subjects.others.next(others);
+
+        this._usersNotifier.others.next({
+            others,
+            event: { kind: "enter", user: added.data },
+        });
     }
 
     private _heartbeat(): void {
@@ -1175,12 +1310,15 @@ export class PluvRoom<
 
         this._updateState((oldState) => {
             oldState.connection.state = ConnectionState.Unavailable;
+            oldState.storage.state = StorageState.Unavailable;
 
             return oldState;
         });
     }
 
     private async _onClose(event: CloseEvent): Promise<void> {
+        this._listenerManager.subjects.close.next(event);
+
         this._logDebug("WebSocket closed");
         if (!!event.reason) this._logDebug(event.reason);
 
@@ -1210,6 +1348,10 @@ export class PluvRoom<
                    * @date April 28, 2025
                    */
                   ConnectionState.Closed;
+            oldState.storage.state =
+                oldState.storage.state === StorageState.Synced
+                    ? StorageState.Offline
+                    : StorageState.Unavailable;
             oldState.webSocket = null;
 
             return oldState;
@@ -1229,9 +1371,13 @@ export class PluvRoom<
      * @description Handle websocket errors in a meaningful way, should they occur
      * @date August 19, 2022
      */
-    private _onError(): void {}
+    private _onError(event: Event): void {
+        this._listenerManager.subjects.error.next(event);
+    }
 
     private _onMessage(event: MessageEvent<string>): void {
+        this._listenerManager.subjects.message.next(event);
+
         const message = this._parseMessage(event);
 
         if (!message) return;
@@ -1288,7 +1434,9 @@ export class PluvRoom<
         }
     }
 
-    private _onOpen(): void {
+    private _onOpen(event: Event): void {
+        this._listenerManager.subjects.open.next(event);
+
         if (this._state.connection.state !== ConnectionState.Connecting) return;
 
         this._logDebug("WebSocket connected");
@@ -1310,6 +1458,10 @@ export class PluvRoom<
 
         this._updateState((oldState) => {
             oldState.connection.state = ConnectionState.Unavailable;
+            oldState.storage.state =
+                oldState.storage.state === StorageState.Synced
+                    ? StorageState.Offline
+                    : StorageState.Unavailable;
 
             return oldState;
         });
@@ -1460,6 +1612,7 @@ export class PluvRoom<
             ...this._state,
             authorization,
             connection: JSON.parse(JSON.stringify(this._state.connection)),
+            storage: JSON.parse(JSON.stringify(this._state.storage)),
             webSocket: this._state.webSocket,
         };