@pluv/crdt-yjs 2.0.2 → 2.2.0

package/src/awareness/PluvYjsAwareness.ts

@@ -0,0 +1,220 @@
+import type {
+    CrdtType,
+    IOLike,
+    OthersSubscriptionEvent,
+    PluvRouterEventConfig,
+    RoomLike,
+    UserInfo,
+} from "@pluv/types";
+import { ObservableV2 } from "lib0/observable";
+import type { Doc as YDoc } from "yjs";
+import { PLUV_PRESENCE_META_KEY, PLUV_PRESENCE_Y_ID_KEY } from "../constants";
+import type { AwarenessPresence, MetaClientState, YjsAwarenessUpdate } from "../types";
+
+export interface PluvYjsAwarenessParams<
+    TIO extends IOLike<any>,
+    TPresence extends Record<string, any>,
+    TStorage extends Record<string, CrdtType<any, any>>,
+    TEvents extends PluvRouterEventConfig,
+    TField extends keyof TPresence | null = null,
+> {
+    field?: TField;
+    room: RoomLike<TIO, YDoc, TPresence, TStorage, TEvents>;
+}
+
+export class PluvYjsAwareness<
+    TIO extends IOLike,
+    TPresence extends Record<string, any>,
+    TStorage extends Record<string, CrdtType<any, any>>,
+    TEvents extends PluvRouterEventConfig,
+    TField extends keyof TPresence | null = null,
+> extends ObservableV2<{
+    change: (updates: YjsAwarenessUpdate, kind: "presence") => void;
+    destroy: (awareness: PluvYjsAwareness<TIO, TPresence, TStorage, TEvents, TField>) => void;
+    update: (updates: YjsAwarenessUpdate, kind: "local" | "presence") => void;
+}> {
+    public readonly doc: YDoc;
+
+    private readonly _field: TField = null as TField;
+    private readonly _idMap = new Map<[connectionId: string][0], [clientID: number][0]>();
+    private readonly _room: RoomLike<TIO, YDoc, TPresence, TStorage, TEvents>;
+    private readonly _unsubscribe: () => void;
+
+    public get clientID(): number {
+        return this.doc.clientID;
+    }
+
+    public get states(): Map<number, TPresence> {
+        return this.getStates();
+    }
+
+    constructor(params: PluvYjsAwarenessParams<TIO, TPresence, TStorage, TEvents, TField>) {
+        super();
+
+        const { field, room } = params;
+
+        this.doc = room.getDoc().value;
+        this._room = room;
+
+        if (!!field) this._field = field;
+
+        const myPresence: any = this._room.getMyPresence();
+        const myMeta = myPresence?.[PLUV_PRESENCE_META_KEY] || {};
+
+        this._room.updateMyPresence({
+            [PLUV_PRESENCE_META_KEY]: {
+                ...myMeta,
+                [PLUV_PRESENCE_Y_ID_KEY]: this.clientID,
+            },
+        } as any);
+
+        this._unsubscribe = this._room.subscribe.others((others, event) => {
+            const updates = this._deriveUpdates(others, event);
+
+            if (!updates) return;
+
+            this.emit("change", [updates, "presence"]);
+            this.emit("update", [updates, "presence"]);
+        });
+    }
+
+    public destroy(): void {
+        this.emit("destroy", [this]);
+        this._unsubscribe();
+        super.destroy();
+    }
+
+    public getLocalState(): AwarenessPresence<TPresence, TField> {
+        return this._adaptPresence(this._room.getMyPresence());
+    }
+
+    public setLocalState(state: AwarenessPresence<TPresence, TField>): void {
+        const patch = (!!this._field
+            ? { [this._field]: state }
+            : state) as unknown as Partial<TPresence>;
+
+        this._room.updateMyPresence(patch);
+
+        this.emit("update", [{ added: [], updated: [this.clientID], removed: [] }, "local"]);
+    }
+
+    public setLocalStateField<TLocalField extends keyof AwarenessPresence<TPresence, TField>>(
+        field: TLocalField,
+        value: AwarenessPresence<TPresence, TField>[TLocalField],
+    ): void {
+        /**
+         * !HACK
+         * @description Cast to unknown first, because field loses its type of TField when set in
+         * an object.
+         * @date May 14, 2025
+         */
+        const patch = (!!this._field
+            ? { [this._field]: { ...this.getLocalState(), [field]: value } }
+            : { [field]: value }) as unknown as Partial<TPresence>;
+
+        this._room.updateMyPresence(patch);
+    }
+
+    /**
+     * !HACK
+     * @description We're building the awareness presences from the states stored on the room's
+     * presense instead of using the map defined in the awareness interface.
+     * @see https://github.com/yjs/y-protocols/blob/master/awareness.js
+     * @date May 13, 2025
+     */
+    public getStates(): Map<number, AwarenessPresence<TPresence, TField>> {
+        const others = this._room.getOthers();
+
+        const states = others.reduce((map, other) => {
+            const presence = this._adaptPresence(other.presence);
+            const meta = other.presence?.[PLUV_PRESENCE_META_KEY] || {};
+            const clientID: number | undefined = meta[PLUV_PRESENCE_Y_ID_KEY];
+
+            return typeof presence !== "undefined" && typeof clientID !== "undefined"
+                ? map.set(clientID, presence)
+                : map;
+        }, new Map<number, AwarenessPresence<TPresence, TField>>());
+
+        const myPresence = this.getLocalState();
+
+        if (typeof myPresence !== "undefined") states.set(this.clientID, myPresence);
+
+        return states;
+    }
+
+    private _adaptPresence(presence: TPresence): AwarenessPresence<TPresence, TField> {
+        return (!!this._field ? presence[this._field] : presence) as AwarenessPresence<
+            TPresence,
+            TField
+        >;
+    }
+
+    private _deriveUpdates(
+        others: readonly UserInfo<any, any>[],
+        event: OthersSubscriptionEvent<any, any>,
+    ): YjsAwarenessUpdate | null {
+        switch (event.kind) {
+            case "clear": {
+                this._idMap.clear();
+                return null;
+            }
+            case "enter": {
+                const clientID = this._resetIdMap(others).get(event.user.connectionId);
+
+                return {
+                    added: typeof clientID !== "undefined" ? [clientID] : [],
+                    updated: [],
+                    removed: [],
+                };
+            }
+            case "leave": {
+                const clientID = this._idMap.get(event.user.connectionId);
+
+                this._resetIdMap(others);
+
+                return {
+                    added: [],
+                    updated: [],
+                    removed: typeof clientID !== "undefined" ? [clientID] : [],
+                };
+            }
+            case "sync": {
+                this._resetIdMap(others);
+                return null;
+            }
+            case "update": {
+                const clientID = this._resetIdMap(others).get(event.user.connectionId);
+
+                return {
+                    added: [],
+                    updated: typeof clientID !== "undefined" ? [clientID] : [],
+                    removed: [],
+                };
+            }
+            default:
+                return null;
+        }
+    }
+
+    private _resetIdMap(others: readonly UserInfo<any, any>[]): Map<string, number> {
+        this._idMap.clear();
+
+        return others.reduce((map, other) => {
+            const clientID = other.presence[PLUV_PRESENCE_META_KEY]?.[PLUV_PRESENCE_Y_ID_KEY];
+
+            if (typeof clientID === "undefined") return map;
+
+            return map.set(other.connectionId, clientID);
+        }, this._idMap);
+    }
+
+    /**
+     * !HACK
+     * @description We dgaf about these. We're just mirroring the fields that exist in the
+     * og awareness to make sure everything aligns.
+     * @see https://github.com/yjs/y-protocols/blob/master/awareness.js
+     * @date May 13, 2025
+     */
+    public readonly meta = new Map<string, MetaClientState>();
+    public readonly _checkInterval: number = 0;
+}

package/src/awareness/awareness.ts

@@ -0,0 +1,15 @@
+import type { CrdtType, IOLike, PluvRouterEventConfig } from "@pluv/types";
+import type { PluvYjsAwarenessParams } from "./PluvYjsAwareness";
+import { PluvYjsAwareness } from "./PluvYjsAwareness";
+
+export const awareness = <
+    TIO extends IOLike<any>,
+    TPresence extends Record<string, any>,
+    TStorage extends Record<string, CrdtType<any, any>>,
+    TEvents extends PluvRouterEventConfig,
+    TField extends keyof TPresence | null = null,
+>(
+    params: PluvYjsAwarenessParams<TIO, TPresence, TStorage, TEvents, TField>,
+): PluvYjsAwareness<TIO, TPresence, TStorage, TEvents, TField> => {
+    return new PluvYjsAwareness(params);
+};

package/src/awareness/index.ts

@@ -0,0 +1,2 @@
+export { awareness } from "./awareness";
+export type { PluvYjsAwareness } from "./PluvYjsAwareness";

package/src/constants.ts

@@ -0,0 +1,2 @@
+export const PLUV_PRESENCE_META_KEY = "__pluv";
+export const PLUV_PRESENCE_Y_ID_KEY = "__y_clientid";

package/src/doc/CrdtYjsDoc.ts

@@ -39,7 +39,7 @@ export type CrdtYjsDocParams<TStorage extends Record<string, YjsType<any, any>>>
 ) => TStorage;
 
 export class CrdtYjsDoc<TStorage extends Record<string, YjsType<any, any>>>
-    implements CrdtDocLike<TStorage>
+    implements CrdtDocLike<YDoc, TStorage>
 {
     public value: YDoc = new YDoc();
 
@@ -285,7 +285,9 @@ export class CrdtYjsDoc<TStorage extends Record<string, YjsType<any, any>>>
         return this;
     }
 
-    public subscribe(listener: (params: DocSubscribeCallbackParams<TStorage>) => void): () => void {
+    public subscribe(
+        listener: (params: DocSubscribeCallbackParams<YDoc, TStorage>) => void,
+    ): () => void {
         const fn = (update: Uint8Array, origin: any, doc: YDoc) => {
             listener({
                 doc: this,

package/src/doc/CrdtYjsDocFactory.ts

@@ -1,11 +1,12 @@
 import { AbstractCrdtDocFactory } from "@pluv/crdt";
+import type { Doc as YDoc } from "yjs";
 import type { YjsType } from "../types";
 import { CrdtYjsDoc } from "./CrdtYjsDoc";
 import type { YjsBuilder } from "./builder";
 
 export class CrdtYjsDocFactory<
     TStorage extends Record<string, YjsType<any, any>> = {},
-> extends AbstractCrdtDocFactory<TStorage> {
+> extends AbstractCrdtDocFactory<YDoc, TStorage> {
     public readonly _initialStorage: (builder: YjsBuilder) => TStorage;
 
     constructor(initialStorage: (builder: YjsBuilder) => TStorage = () => ({}) as TStorage) {

package/src/provider/PluvYjsProvider.ts

@@ -0,0 +1,132 @@
+import type { CrdtType, IOLike, PluvRouterEventConfig, RoomLike } from "@pluv/types";
+import { StorageState } from "@pluv/types";
+import { ObservableV2 } from "lib0/observable";
+import type { Doc as YDoc } from "yjs";
+import type { PluvYjsAwareness } from "../awareness";
+import { awareness } from "../awareness";
+import type { YjsProviderStatus } from "../types";
+
+export interface PluvYjsProviderParams<
+    TIO extends IOLike<any>,
+    TPresence extends Record<string, any>,
+    TStorage extends Record<string, CrdtType<any, any>>,
+    TEvents extends PluvRouterEventConfig,
+    TField extends keyof TPresence | null = null,
+> {
+    field?: TField;
+    room: RoomLike<TIO, YDoc, TPresence, TStorage, TEvents>;
+}
+
+/**
+ * !HACK
+ * @description This doesn't really do anything but emit states in a Yjs.Provider compatible way.
+ * Connections and document syncing are handled by the PluvRoom already.
+ * @date May 13, 2025
+ */
+export class PluvYjsProvider<
+    TIO extends IOLike<any>,
+    TPresence extends Record<string, any>,
+    TStorage extends Record<string, CrdtType<any, any>>,
+    TEvents extends PluvRouterEventConfig,
+    TField extends keyof TPresence | null = null,
+> extends ObservableV2<{
+    "connection-close": (
+        event: CloseEvent | null,
+        provider: PluvYjsProvider<TIO, TPresence, TStorage, TEvents, TField>,
+    ) => void;
+    "connection-error": (
+        event: Event,
+        provider: PluvYjsProvider<TIO, TPresence, TStorage, TEvents, TField>,
+    ) => void;
+    status: (event: { status: YjsProviderStatus }) => void;
+    sync: (state: boolean) => void;
+    synced: (state: boolean) => void;
+}> {
+    public readonly awareness: PluvYjsAwareness<TIO, TPresence, TStorage, TEvents, TField>;
+    public readonly doc: YDoc;
+
+    private readonly _room: RoomLike<TIO, YDoc, TPresence, TStorage, TEvents>;
+    private readonly _unsubscribe: () => void;
+
+    private _synced: boolean = false;
+
+    constructor(params: PluvYjsProviderParams<TIO, TPresence, TStorage, TEvents, TField>) {
+        super();
+
+        const { field, room } = params;
+
+        this.awareness = awareness({ field, room });
+        this.doc = room.getDoc().value;
+
+        this._room = room;
+
+        const subscriptions = [
+            this._room.subscribe.connection(({ storage }) => {
+                const status = this._toProviderStatus(storage.state);
+
+                if (!status) return;
+
+                this.emit("status", [{ status }]);
+            }),
+            this._room.addEventListener("close", (event) => {
+                this.emit("connection-close", [event, this]);
+            }),
+            this._room.addEventListener("error", (event) => {
+                this.emit("connection-error", [event, this]);
+            }),
+        ];
+
+        this._unsubscribe = subscriptions.reduce(
+            (fn, unsubscribe) => () => {
+                fn();
+                unsubscribe();
+            },
+            () => undefined,
+        );
+    }
+
+    public get synced(): boolean {
+        return this._synced;
+    }
+
+    public set synced(state: boolean) {
+        if (this._synced === state) return;
+
+        this._synced = state;
+        this.emit("sync", [state]);
+        this.emit("synced", [state]);
+    }
+
+    public destroy(): void {
+        this.awareness.destroy();
+        this._unsubscribe();
+        super.destroy();
+    }
+
+    private _toProviderStatus(state: StorageState): YjsProviderStatus | null {
+        switch (state) {
+            case StorageState.Loading: {
+                return "connecting";
+            }
+            case StorageState.Unavailable: {
+                return "disconnected";
+            }
+            case StorageState.Offline:
+            case StorageState.Synced: {
+                return "connected";
+            }
+            default:
+                return null;
+        }
+    }
+
+    /**
+     * !HACK
+     * @description We dgaf about these, since the room manages these already. We're just mirroring
+     * the fields that exist in the og provider to make sure everything aligns.
+     * @see https://github.com/yjs/y-websocket/blob/master/src/y-websocket.js
+     * @date May 13, 2025
+     */
+    public connect(): void {}
+    public disconnect(): void {}
+}

package/src/provider/index.ts

@@ -0,0 +1,2 @@
+export type { PluvYjsProvider } from "./PluvYjsProvider";
+export { provider } from "./provider";

package/src/provider/provider.ts

@@ -0,0 +1,15 @@
+import type { CrdtType, IOLike, PluvRouterEventConfig } from "@pluv/types";
+import type { PluvYjsProviderParams } from "./PluvYjsProvider";
+import { PluvYjsProvider } from "./PluvYjsProvider";
+
+export const provider = <
+    TIO extends IOLike<any>,
+    TPresence extends Record<string, any>,
+    TStorage extends Record<string, CrdtType<any, any>>,
+    TEvents extends PluvRouterEventConfig,
+    TField extends keyof TPresence | null = null,
+>(
+    params: PluvYjsProviderParams<TIO, TPresence, TStorage, TEvents, TField>,
+) => {
+    return new PluvYjsProvider(params);
+};

package/src/types.ts

@@ -7,3 +7,29 @@ export type YjsType<TValue extends unknown, TJson extends unknown = any> = CrdtT
     initialValue?: any;
     toJSON: () => any;
 };
+
+/**
+ * @description Type internally defined by Yjs.Awareness
+ * @see https://github.com/yjs/y-protocols/blob/master/awareness.js
+ */
+export interface YjsAwarenessUpdate {
+    added: number[];
+    updated: number[];
+    removed: number[];
+}
+
+export type YjsProviderStatus = "connecting" | "connected" | "disconnected";
+
+/**
+ * @description Type internally defined by Yjs.Awareness
+ * @see https://github.com/yjs/y-protocols/blob/master/awareness.js
+ */
+export interface MetaClientState {
+    clock: number;
+    lastUpdated: number;
+}
+
+export type AwarenessPresence<
+    TPresence extends Record<string, any>,
+    TField extends keyof TPresence | null,
+> = TField extends null ? TPresence : TField extends keyof TPresence ? TPresence[TField] : never;

package/src/yjs.ts

@@ -1,8 +1,10 @@
 export { array } from "./array";
+export { awareness } from "./awareness";
 export { doc } from "./doc";
 export type { YjsBuilder } from "./doc";
 export { map } from "./map";
 export { object } from "./object";
+export { provider } from "./provider";
 export { text } from "./text";
 export type { YjsType } from "./types";
 export { xmlElement } from "./xmlElement";