@pluv/crdt-yjs 5.0.1 → 5.0.2

package/eslint.config.mjs

@@ -1,4 +0,0 @@
-import { config } from "eslint-config-pluv/base";
-
-/** @type {import("eslint").Linter.Config} */
-export default config;

package/src/array/YjsArray.ts

@@ -1,18 +0,0 @@
-import { Array as YArray } from "yjs";
-import type { YjsType } from "../types";
-
-export class YjsArray<T extends unknown> extends YArray<T> implements YjsType<YArray<T>, T[]> {
-    public initialValue?: T[] | readonly T[];
-
-    constructor(value: T[] | readonly T[] = []) {
-        super();
-
-        this.insert(0, value as T[]);
-
-        this.initialValue = value;
-    }
-
-    public __pluvType() {
-        return {} as any;
-    }
-}

package/src/array/array.ts

@@ -1,9 +0,0 @@
-import { Array as YArray } from "yjs";
-import type { YjsType } from "../types";
-import { YjsArray } from "./YjsArray";
-
-export const array = <T extends unknown>(
-    value: T[] | readonly T[] = [],
-): YjsType<YArray<T>, T[]> => {
-    return new YjsArray(value);
-};

package/src/array/index.ts

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

package/src/awareness/PluvYjsAwareness.ts

@@ -1,220 +0,0 @@
-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, any, any>,
-    TPresence extends Record<string, any>,
-    TStorage extends Record<string, CrdtType<any, any>>,
-    TEvents extends PluvRouterEventConfig,
-    TField extends keyof TPresence | null = null,
-> {
-    presenceField?: 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 { presenceField, room } = params;
-
-        this.doc = room.getDoc().value;
-        this._room = room;
-
-        if (!!presenceField) this._field = presenceField;
-
-        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<any, MetaClientState>();
-    public readonly _checkInterval: number = 0;
-}

package/src/awareness/awareness.ts

@@ -1,15 +0,0 @@
-import type { CrdtType, IOLike, PluvRouterEventConfig } from "@pluv/types";
-import type { PluvYjsAwarenessParams } from "./PluvYjsAwareness";
-import { PluvYjsAwareness } from "./PluvYjsAwareness";
-
-export const awareness = <
-    TIO extends IOLike<any, any, 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

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

package/src/constants.ts

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

package/src/doc/CrdtYjsDoc.ts

@@ -1,241 +0,0 @@
-import type {
-    DocApplyEncodedStateParams,
-    DocBatchApplyEncodedStateParams,
-    DocSubscribeCallbackParams,
-    InferCrdtJson,
-} from "@pluv/crdt";
-import type { CrdtDocLike } from "@pluv/types";
-import { fromUint8Array, toUint8Array } from "js-base64";
-import {
-    AbstractType,
-    UndoManager,
-    Array as YArray,
-    Doc as YDoc,
-    Map as YMap,
-    Text as YText,
-    XmlElement as YXmlElement,
-    XmlFragment as YXmlFragment,
-    XmlText as YXmlText,
-    applyUpdate,
-    encodeStateAsUpdate,
-    mergeUpdates,
-} from "yjs";
-import type { YjsType } from "../types";
-import type { YjsBuilder } from "./builder";
-import { builder } from "./builder";
-
-const MERGE_INTERVAL_MS = 1_000;
-const PLUV_ID_FIELD = "__$pluv";
-
-export type CrdtYjsDocParams<TStorage extends Record<string, YjsType<any, any>>> = (
-    builder: YjsBuilder,
-) => TStorage;
-
-export class CrdtYjsDoc<TStorage extends Record<string, YjsType<any, any>>> implements CrdtDocLike<
-    YDoc,
-    TStorage
-> {
-    public value: YDoc = new YDoc();
-
-    #_storage: TStorage;
-    #_undoManager: UndoManager | null = null;
-
-    constructor(params: CrdtYjsDocParams<TStorage> = () => ({}) as TStorage) {
-        const storage = params(builder(this.value));
-        const keys = this.value.share.keys().reduce((set, key) => set.add(key), new Set<string>());
-
-        this.#_storage = Object.entries(storage).reduce(
-            (acc, [key, node]) => (keys.has(key) ? { ...acc, [key]: node } : acc),
-            {} as TStorage,
-        );
-        if (!!Object.keys(storage).length) this.#_setPluvId();
-    }
-
-    public applyEncodedState(params: DocApplyEncodedStateParams): this {
-        const { origin, update } = params;
-
-        if (update === null || typeof update === "undefined") return this;
-
-        const uint8Update = typeof update === "string" ? toUint8Array(update) : update;
-
-        applyUpdate(this.value, uint8Update, origin);
-
-        return this;
-    }
-
-    public batchApplyEncodedState(params: DocBatchApplyEncodedStateParams): this {
-        const { origin } = params;
-        const updates = params.updates ?? [];
-
-        const filtered = updates.reduce<Uint8Array[]>((acc, update) => {
-            if (!update) return acc;
-
-            if (typeof update === "string") {
-                acc.push(toUint8Array(update));
-                return acc;
-            }
-
-            if (typeof update === "object") {
-                acc.push(update);
-                return acc;
-            }
-
-            return acc;
-        }, []);
-
-        if (!filtered.length) return this;
-
-        const merged = mergeUpdates(filtered);
-
-        return this.applyEncodedState({ origin, update: merged });
-    }
-
-    public canRedo(): boolean {
-        return !!this.#_undoManager?.canRedo();
-    }
-
-    public canUndo(): boolean {
-        return !!this.#_undoManager?.canUndo();
-    }
-
-    public destroy(): void {
-        this.#_undoManager?.destroy();
-        this.value.destroy();
-    }
-
-    public get(key?: undefined): TStorage;
-    public get<TKey extends keyof TStorage>(type: TKey): TStorage[TKey];
-    public get<TKey extends keyof TStorage>(type?: TKey): TStorage | TStorage[TKey] {
-        if (typeof type === "undefined") return this.#_storage;
-
-        return this.#_storage[type as TKey];
-    }
-
-    public getEncodedState(): string {
-        return fromUint8Array(encodeStateAsUpdate(this.value));
-    }
-
-    public isEmpty(): boolean {
-        return !this.value.share.size;
-    }
-
-    public rebuildStorage(reference: TStorage): this {
-        const isBuilt = !!Object.keys(this.#_storage).length;
-
-        if (isBuilt) {
-            console.warn("Attempted to rebuild storage multiple times");
-            return this;
-        }
-
-        this.#_storage = Object.entries(reference).reduce((acc, [key, node]) => {
-            /**
-             * @description It is important that the XML shared-types be checked before the others
-             * because they extend off the non-xml types (thereby you can mistakenly identify the
-             * wrong type if checked in the reverse order)
-             * @date May 9 ,2025
-             */
-            if (node instanceof YXmlElement) {
-                return { ...acc, [key]: this.value.getXmlElement(key) };
-            }
-            if (node instanceof YXmlFragment) {
-                return { ...acc, [key]: this.value.getXmlFragment(key) };
-            }
-            if (node instanceof YXmlText) return { ...acc, [key]: this.value.get(key, YXmlText) };
-            if (node instanceof YArray) return { ...acc, [key]: this.value.getArray(key) };
-            if (node instanceof YMap) return { ...acc, [key]: this.value.getMap(key) };
-            if (node instanceof YText) return { ...acc, [key]: this.value.getText(key) };
-
-            return acc;
-        }, {} as TStorage);
-
-        return this.track();
-    }
-
-    public redo(): this {
-        this.#_undoManager?.redo();
-
-        return this;
-    }
-
-    public subscribe(
-        listener: (params: DocSubscribeCallbackParams<YDoc, TStorage>) => void,
-    ): () => void {
-        const fn = (update: Uint8Array, origin: any, doc: YDoc) => {
-            listener({
-                doc: this,
-                local: origin === null || typeof origin === "undefined",
-                origin: origin ? String(origin) : null,
-                update: fromUint8Array(update),
-            });
-        };
-
-        this.value.on("update", fn);
-
-        return () => {
-            this.value.off("update", fn);
-        };
-    }
-
-    public track(): this {
-        if (this.#_undoManager) this.#_undoManager.destroy();
-
-        const sharedTypes = Object.values(this.#_storage).reduce<YjsType<AbstractType<any>, any>[]>(
-            (acc, type) => {
-                if (
-                    type instanceof YArray ||
-                    type instanceof YMap ||
-                    type instanceof YText ||
-                    type instanceof YXmlElement ||
-                    type instanceof YXmlFragment ||
-                    type instanceof YXmlText
-                ) {
-                    acc.push(type as YjsType<AbstractType<any>, any>);
-                }
-
-                return acc;
-            },
-            [],
-        );
-
-        if (!sharedTypes.length) {
-            this.#_undoManager?.destroy();
-            this.#_undoManager = null;
-
-            return this;
-        }
-
-        this.#_undoManager = new UndoManager(sharedTypes, { captureTimeout: MERGE_INTERVAL_MS });
-
-        return this;
-    }
-
-    public transact(fn: () => void): this {
-        this.value.transact(fn);
-
-        return this;
-    }
-
-    public toJson(): InferCrdtJson<TStorage>;
-    public toJson<TKey extends keyof TStorage>(type: TKey): InferCrdtJson<TStorage[TKey]>;
-    public toJson<TKey extends keyof TStorage>(type?: TKey) {
-        if (typeof type === "string") return this.#_storage[type].toJSON();
-
-        return Object.entries(this.#_storage).reduce(
-            (acc, [key, value]) => ({ ...(acc as any), [key]: value.toJSON() }),
-            {} as InferCrdtJson<TStorage>,
-        );
-    }
-
-    public undo(): this {
-        this.#_undoManager?.undo();
-
-        return this;
-    }
-
-    #_setPluvId() {
-        const text = this.value.getText(PLUV_ID_FIELD);
-        const id = typeof crypto !== "undefined" ? crypto.randomUUID() : Math.random().toString();
-
-        text.insert(0, id);
-    }
-}

package/src/doc/CrdtYjsDocFactory.ts

@@ -1,33 +0,0 @@
-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<YDoc, TStorage> {
-    public readonly _initialStorage: (builder: YjsBuilder) => TStorage;
-
-    constructor(initialStorage: (builder: YjsBuilder) => TStorage = () => ({}) as TStorage) {
-        super(initialStorage);
-
-        this._initialStorage = initialStorage;
-    }
-
-    public getEmpty(): CrdtYjsDoc<TStorage> {
-        return new CrdtYjsDoc<TStorage>();
-    }
-
-    public getFactory(
-        initialStorage: (builder: YjsBuilder) => TStorage,
-    ): CrdtYjsDocFactory<TStorage> {
-        return new CrdtYjsDocFactory<TStorage>(initialStorage ?? this._initialStorage);
-    }
-
-    public getInitialized(
-        initialStorage?: (builder: YjsBuilder) => TStorage,
-    ): CrdtYjsDoc<TStorage> {
-        return new CrdtYjsDoc<TStorage>(initialStorage ?? this._initialStorage);
-    }
-}

package/src/doc/builder.ts

@@ -1,71 +0,0 @@
-import {
-    Array as YArray,
-    Doc as YDoc,
-    Map as YMap,
-    Text as YText,
-    XmlElement as YXmlElement,
-    XmlFragment as YXmlFragment,
-    XmlText as YXmlText,
-} from "yjs";
-import { YjsType } from "../types";
-
-export type YjsBuilder = ReturnType<typeof builder>;
-
-export const builder = (doc: YDoc) => {
-    return {
-        array<T extends unknown>(
-            name: string,
-            value: T[] | readonly T[] = [],
-        ): YjsType<YArray<T>, T[]> {
-            const array = doc.getArray<T>(name);
-
-            if (!!value.length) array.insert(0, value as T[]);
-
-            return array as unknown as YjsType<YArray<T>, T[]>;
-        },
-        map<T extends unknown>(
-            name: string,
-            value: readonly (readonly [key: string, value: T])[] = [],
-        ): YjsType<YMap<T>, Record<string, T>> {
-            const map = doc.getMap(name);
-
-            value.forEach(([k, v]) => {
-                map.set(k, v);
-            });
-
-            return map as unknown as YjsType<YMap<T>, Record<string, T>>;
-        },
-        text(name: string, value: string = ""): YjsType<YText, string> {
-            const text = doc.getText(name);
-
-            if (!!value) text.insert(0, value);
-
-            return text as unknown as YjsType<YText, string>;
-        },
-        xmlElement(
-            name: string,
-            children: (YXmlElement | YXmlText)[] | readonly (YXmlElement | YXmlText)[] = [],
-        ): YjsType<YXmlElement, string> {
-            const xmlElement = doc.getXmlElement(name);
-
-            if (!!children.length) xmlElement.insert(0, children as (YXmlElement | YXmlText)[]);
-
-            return xmlElement as unknown as YjsType<YXmlElement, string>;
-        },
-        xmlFragment(
-            name: string,
-            children: (YXmlElement | YXmlText)[] | readonly (YXmlElement | YXmlText)[] = [],
-        ): YjsType<YXmlFragment, string> {
-            const xmlFragment = doc.getXmlFragment(name);
-
-            if (!!children.length) xmlFragment.insert(0, children as (YXmlElement | YXmlText)[]);
-
-            return xmlFragment as unknown as YjsType<YXmlFragment, string>;
-        },
-        xmlText(name: string): YjsType<YXmlText, string> {
-            const xmlText = doc.get(name, YXmlText);
-
-            return xmlText as unknown as YjsType<YXmlText, string>;
-        },
-    };
-};

package/src/doc/doc.ts

@@ -1,9 +0,0 @@
-import type { YjsType } from "../types";
-import type { YjsBuilder } from "./builder";
-import { CrdtYjsDocFactory } from "./CrdtYjsDocFactory";
-
-export const doc = <TStorage extends Record<string, YjsType<any, any>>>(
-    value: (buidler: YjsBuilder) => TStorage = () => ({}) as TStorage,
-): CrdtYjsDocFactory<TStorage> => {
-    return new CrdtYjsDocFactory<TStorage>(value);
-};

package/src/doc/index.ts

@@ -1,4 +0,0 @@
-export type { YjsBuilder } from "./builder";
-export { CrdtYjsDoc } from "./CrdtYjsDoc";
-export { CrdtYjsDocFactory } from "./CrdtYjsDocFactory";
-export { doc } from "./doc";

package/src/index.ts

@@ -1,5 +0,0 @@
-import * as yjs from "./yjs";
-
-export * as yjs from "./yjs";
-
-export type YjsLibraryType = typeof yjs;

package/src/map/YjsMap.ts

@@ -1,19 +0,0 @@
-import { Map as YMap } from "yjs";
-import type { YjsType } from "../types";
-
-export class YjsMap<T extends unknown>
-    extends YMap<T>
-    implements YjsType<YMap<T>, Record<string, T>>
-{
-    public initialValue?: readonly (readonly [key: string, value: T])[];
-
-    constructor(value: readonly (readonly [key: string, value: T])[] = []) {
-        super(value);
-
-        this.initialValue = value;
-    }
-
-    public __pluvType(): any {
-        return {} as any;
-    }
-}

package/src/map/index.ts

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

package/src/map/map.ts

@@ -1,9 +0,0 @@
-import type { Map as YMap } from "yjs";
-import type { YjsType } from "../types";
-import { YjsMap } from "./YjsMap";
-
-export const map = <T extends unknown>(
-    value: readonly (readonly [key: string, value: T])[] = [],
-): YjsType<YMap<T>, Record<string, T>> => {
-    return new YjsMap<T>(value) as YjsType<YMap<T>, Record<string, T>>;
-};