@pluv/client 2.0.1 → 2.1.0

package/src/PluvRoom.ts

@@ -1,6 +1,5 @@
 import type {
     AbstractCrdtDocFactory,
-    CrdtType,
     InferCrdtJson,
     InferStorage,
     NoopCrdtDocFactory,
@@ -8,9 +7,11 @@ import type {
 import type {
     BaseIOEventRecord,
     BaseUser,
+    BroadcastProxy,
     CrdtDocLike,
     EventMessage,
     EventNotifierSubscriptionCallback,
+    EventProxy,
     IOEventMessage,
     IOLike,
     Id,
@@ -22,8 +23,15 @@ import type {
     JsonObject,
     MergeEvents,
     OptionalProps,
-    OtherNotifierSubscriptionCallback,
+    OtherSubscriptionCallback,
+    OthersSubscriptionCallback,
     RoomLike,
+    StateNotifierSubjects,
+    StorageProxy,
+    StorageRootSubscriptionCallback,
+    StorageSubscriptionCallback,
+    SubscribeProxy,
+    SubscriptionCallback,
     UpdateMyPresenceAction,
     UserInfo,
     WebSocketState,
@@ -34,11 +42,9 @@ import type { CrdtManagerOptions } from "./CrdtManager";
 import { CrdtManager } from "./CrdtManager";
 import { CrdtNotifier } from "./CrdtNotifier";
 import { EventNotifier } from "./EventNotifier";
-import { OtherNotifier } from "./OtherNotifier";
 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 {
@@ -53,6 +59,7 @@ import type {
 } 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;
@@ -214,7 +221,6 @@ export class PluvRoom<
     };
     private readonly _limits: PluvClientLimits;
     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 +234,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> = {
@@ -364,14 +371,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();
@@ -470,6 +470,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,14 +485,7 @@ 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
@@ -542,42 +538,104 @@ export class PluvRoom<
         return this._crdtManager.doc.toJson(type);
     }
 
+    /**
+     * @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. 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 +737,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 +900,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 +958,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 +1017,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> {
@@ -1083,6 +1173,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 +1212,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 {

package/src/StateNotifier.ts

@@ -1,15 +1,15 @@
-import type { Id, IOLike, JsonObject, UserInfo, WebSocketState } from "@pluv/types";
+import type {
+    Id,
+    IOLike,
+    JsonObject,
+    StateNotifierSubjects,
+    SubscriptionCallback,
+    UserInfo,
+    WebSocketState,
+} from "@pluv/types";
 import type { Subject } from "wonka";
 import { makeSubject, subscribe } from "wonka";
 
-export interface StateNotifierSubjects<TIO extends IOLike, TPresence extends JsonObject> {
-    connection: Subject<Id<WebSocketState<TIO>>>;
-    "my-presence": Subject<TPresence | null>;
-    myself: Subject<Readonly<Id<UserInfo<TIO>>> | null>;
-    others: Subject<readonly Id<UserInfo<TIO>>[]>;
-    "storage-loaded": Subject<boolean>;
-}
-
 type InferSubjectValue<
     TIO extends IOLike,
     TPresence extends JsonObject,
@@ -19,18 +19,12 @@ type InferSubjectValue<
         ? Id<IValue>
         : never;
 
-export type SubscriptionCallback<
-    TIO extends IOLike,
-    TPresence extends JsonObject,
-    TSubject extends keyof StateNotifierSubjects<TIO, TPresence>,
-> = (value: InferSubjectValue<TIO, TPresence, TSubject>) => void;
-
 export class StateNotifier<TIO extends IOLike, TPresence extends JsonObject = {}> {
     public subjects: StateNotifierSubjects<TIO, TPresence> = {
         connection: makeSubject<Id<WebSocketState<TIO>>>(),
         "my-presence": makeSubject<TPresence>(),
-        myself: makeSubject<Readonly<Id<UserInfo<TIO>>> | null>(),
-        others: makeSubject<readonly Id<UserInfo<TIO>>[]>(),
+        myself: makeSubject<Readonly<Id<UserInfo<TIO, TPresence>>> | null>(),
+        others: makeSubject<readonly Id<UserInfo<TIO, TPresence>>[]>(),
         "storage-loaded": makeSubject<true>(),
     };
 

package/src/UsersNotifier.ts

@@ -0,0 +1,66 @@
+import type {
+    Id,
+    IOLike,
+    JsonObject,
+    OtherSubscriptionCallback,
+    OthersSubscriptionCallback,
+    OthersSubscriptionEvent,
+    UserInfo,
+} from "@pluv/types";
+import type { Subject } from "wonka";
+import { makeSubject, subscribe, TypeOfSource } from "wonka";
+
+export class UsersNotifier<TIO extends IOLike, TPresence extends JsonObject = {}> {
+    public readonly others = makeSubject<{
+        others: readonly Id<UserInfo<TIO, TPresence>>[];
+        event: OthersSubscriptionEvent<TIO, TPresence>;
+    }>();
+
+    private _otherSubjects = new Map<
+        [clientId: string][0],
+        Subject<Id<UserInfo<TIO, TPresence>> | null>
+    >();
+
+    public clear(): void {
+        this._otherSubjects.forEach((subject) => {
+            subject.next(null);
+        });
+
+        this._otherSubjects.clear();
+    }
+
+    public delete(clientId: string): void {
+        this.other(clientId).next(null);
+        this._otherSubjects.delete(clientId);
+    }
+
+    public other(clientId: string): Subject<Id<UserInfo<TIO, TPresence>> | null> {
+        const subject = this._otherSubjects.get(clientId);
+
+        if (subject) return subject;
+
+        const newSubject = makeSubject<Id<UserInfo<TIO, TPresence>>>();
+
+        this._otherSubjects.set(clientId, newSubject);
+
+        return newSubject;
+    }
+
+    public subscribeOther(
+        clientId: string,
+        callback: OtherSubscriptionCallback<TIO, TPresence>,
+    ): () => void {
+        const source = this.other(clientId).source;
+        const subscription = subscribe(callback)(source);
+
+        return subscription.unsubscribe;
+    }
+
+    public subscribeOthers(callback: OthersSubscriptionCallback<TIO, TPresence>): () => void {
+        const subscription = subscribe<TypeOfSource<typeof this.others.source>>(
+            ({ others, event }) => callback(others, event),
+        )(this.others.source);
+
+        return subscription.unsubscribe;
+    }
+}

package/src/OtherNotifier.ts

@@ -1,50 +0,0 @@
-import type {
-    Id,
-    IOLike,
-    JsonObject,
-    OtherNotifierSubscriptionCallback,
-    UserInfo,
-} from "@pluv/types";
-import type { Subject } from "wonka";
-import { makeSubject, subscribe } from "wonka";
-
-export class OtherNotifier<TIO extends IOLike, TPresence extends JsonObject = {}> {
-    private _subjects = new Map<
-        [clientId: string][0],
-        Subject<Id<UserInfo<TIO, TPresence>> | null>
-    >();
-
-    public clear(): void {
-        this._subjects.forEach((subject) => {
-            subject.next(null);
-        });
-
-        this._subjects.clear();
-    }
-
-    public delete(clientId: string): void {
-        this.subject(clientId).next(null);
-        this._subjects.delete(clientId);
-    }
-
-    public subject(clientId: string): Subject<Id<UserInfo<TIO, TPresence>> | null> {
-        const subject = this._subjects.get(clientId);
-
-        if (subject) return subject;
-
-        const newSubject = makeSubject<Id<UserInfo<TIO, TPresence>>>();
-
-        this._subjects.set(clientId, newSubject);
-
-        return newSubject;
-    }
-
-    public subscribe(
-        clientId: string,
-        callback: OtherNotifierSubscriptionCallback<TIO, TPresence>,
-    ): () => void {
-        const source = this.subject(clientId).source;
-
-        return subscribe(callback)(source).unsubscribe;
-    }
-}