@pluv/client 5.0.1 → 5.0.3

package/src/PluvRouter.ts

@@ -1,71 +0,0 @@
-import type { AbstractCrdtDocFactory } from "@pluv/crdt";
-import type { IOLike, IORouterLike, JsonObject } from "@pluv/types";
-import type { PluvProcedure } from "./PluvProcedure";
-
-export type PluvRouterEventConfig<
-    TIO extends IOLike,
-    TPresence extends Record<string, any>,
-    TCrdt extends AbstractCrdtDocFactory<any, any>,
-> = { [P: string]: Pick<PluvProcedure<TIO, any, any, TPresence, TCrdt, "">, "config"> };
-
-export type MergedRouter<
-    TRouters extends PluvRouter<TIO, TPresence, TCrdt, any>[],
-    TIO extends IOLike,
-    TPresence extends Record<string, any>,
-    TCrdt extends AbstractCrdtDocFactory<any, any>,
-    TRoot extends TRouters[0]["_defs"]["events"],
-> = TRouters extends [
-    infer IHead extends PluvRouter<TIO, TPresence, TCrdt, any>,
-    ...infer ITail extends PluvRouter<TIO, TPresence, TCrdt, any>[],
-]
-    ? MergedRouter<ITail, TIO, TPresence, TCrdt, TRoot & IHead["_defs"]["events"]>
-    : PluvRouter<TIO, TPresence, TCrdt, TRoot>;
-
-export class PluvRouter<
-    TIO extends IOLike,
-    TPresence extends Record<string, any>,
-    TCrdt extends AbstractCrdtDocFactory<any, any>,
-    TEvents extends PluvRouterEventConfig<TIO, TPresence, TCrdt> = {},
-> implements IORouterLike<TEvents> {
-    readonly _defs: { events: TEvents } = { events: {} as TEvents };
-
-    constructor(events: TEvents) {
-        const invalidName = Object.keys(events).find((name) => !this._isValidEventName(name));
-
-        if (typeof invalidName === "string") {
-            throw new Error(
-                `Invalid event name. Event names must be formatted as valid JavaScript variable names: "${invalidName}"`,
-            );
-        }
-
-        this._defs = { events };
-    }
-
-    public static merge<
-        TRouters extends PluvRouter<TIO, TPresence, TCrdt, any>[],
-        TIO extends IOLike,
-        TPresence extends Record<string, any>,
-        TCrdt extends AbstractCrdtDocFactory<any, any>,
-    >(...routers: TRouters): MergedRouter<TRouters, TIO, TPresence, TCrdt, {}> {
-        const events = Object.assign(
-            Object.create(null),
-            ...routers.map((router) => router._defs.events),
-        );
-
-        if (Object.keys(events).some((key) => key.startsWith("$"))) {
-            throw new Error('Procedures may not start with "$"');
-        }
-
-        return new PluvRouter<any, any, any, any>(events) as MergedRouter<
-            TRouters,
-            TIO,
-            TPresence,
-            TCrdt,
-            {}
-        >;
-    }
-
-    private _isValidEventName(name: string): boolean {
-        return /^[a-z_$][a-z0-9_$]*$/gi.test(name);
-    }
-}

package/src/StateNotifier.ts

@@ -1,41 +0,0 @@
-import type {
-    Id,
-    IOLike,
-    JsonObject,
-    StateNotifierSubjects,
-    SubscriptionCallback,
-    UserInfo,
-    WebSocketState,
-} from "@pluv/types";
-import type { Subject } from "wonka";
-import { makeSubject, subscribe } from "wonka";
-
-type InferSubjectValue<
-    TIO extends IOLike,
-    TPresence extends Record<string, any>,
-    TSubject extends keyof StateNotifierSubjects<TIO, TPresence>,
-> =
-    StateNotifierSubjects<TIO, TPresence>[TSubject] extends Subject<infer IValue>
-        ? Id<IValue>
-        : never;
-
-export class StateNotifier<TIO extends IOLike, TPresence extends Record<string, any> = {}> {
-    public subjects: StateNotifierSubjects<TIO, TPresence> = {
-        connection: makeSubject<Id<WebSocketState<TIO>>>(),
-        "my-presence": makeSubject<TPresence>(),
-        myself: makeSubject<Readonly<Id<UserInfo<TIO, TPresence>>> | null>(),
-        others: makeSubject<readonly Id<UserInfo<TIO, TPresence>>[]>(),
-        "storage-loaded": makeSubject<true>(),
-    };
-
-    public subscribe<TSubject extends keyof StateNotifierSubjects<TIO, TPresence>>(
-        name: TSubject,
-        callback: SubscriptionCallback<TIO, TPresence, TSubject>,
-    ): () => void {
-        const source = this.subjects[name]?.source as any;
-
-        if (!source) throw new Error(`Could not subscribe to source: ${name}`);
-
-        return subscribe(callback)(source).unsubscribe;
-    }
-}

package/src/StorageStore.ts

@@ -1,31 +0,0 @@
-import { AbstractStorageStore } from "./AbstractStorageStore";
-
-export class StorageStore extends AbstractStorageStore {
-    public addUpdate() {
-        return Promise.resolve();
-    }
-
-    public applyUpdates() {
-        return Promise.resolve();
-    }
-
-    public destroy() {
-        return Promise.resolve();
-    }
-
-    public flatten() {
-        return Promise.resolve();
-    }
-
-    public getShouldFlatten() {
-        return Promise.resolve(false);
-    }
-
-    public getUpdates() {
-        return Promise.resolve([]);
-    }
-
-    public initialize() {
-        return Promise.resolve();
-    }
-}

package/src/UsersManager.ts

@@ -1,341 +0,0 @@
-import type { InputZodLike, IOLike, JsonObject, OptionalProps, UserInfo } from "@pluv/types";
-import { PLUV_PRESENCE_META_KEY } from "./constants";
-import type { PluvClientLimits } from "./types";
-import { pickBy } from "./utils";
-
-export type Presence = Record<string, unknown>;
-
-export type UsersManagerConfig<TPresence extends Record<string, any> = {}> = {
-    initialPresence?: TPresence;
-    limits: PluvClientLimits;
-    presence?: InputZodLike<TPresence>;
-};
-
-export type AddConnectionResult<TIO extends IOLike, TPresence extends Record<string, any> = {}> = {
-    clientId: string;
-    data: UserInfo<TIO, TPresence>;
-    isMyself: boolean;
-    remaining: number;
-};
-
-export type DeleteConnectionResult<
-    TIO extends IOLike,
-    TPresence extends Record<string, any> = {},
-> = {
-    clientId: string;
-    data: UserInfo<TIO, TPresence>;
-    remaining: number;
-};
-
-export class UsersManager<TIO extends IOLike, TPresence extends Record<string, any> = {}> {
-    public readonly initialPresence: TPresence;
-
-    private readonly _idMap = {
-        fromConnectionId: new Map<[connectionId: string][0], [clientId: string][0]>(),
-        fromClientId: new Map<[clientId: string][0], Set<[connectionId: string][0]>>(),
-    };
-    private _limits: PluvClientLimits;
-    /**
-     * @description This presence can be updated while the user is not
-     * connected.
-     */
-    private _myPresence: TPresence;
-    /**
-     * @description This is only set when the user is connected.
-     */
-    private _myself: UserInfo<TIO, TPresence> | null = null;
-    private _others = new Map<[clientId: string][0], UserInfo<TIO, TPresence>>();
-    private _presence: InputZodLike<TPresence> | null = null;
-
-    constructor(config: UsersManagerConfig<TPresence>) {
-        const { initialPresence, limits, presence = null } = config;
-
-        this.initialPresence = initialPresence as TPresence;
-
-        this._limits = limits;
-        this._myPresence = initialPresence as TPresence;
-        this._presence = presence;
-    }
-
-    public get myPresence(): TPresence {
-        return this._myPresence;
-    }
-
-    public get myself(): UserInfo<TIO, TPresence> | null {
-        return this._myself;
-    }
-
-    public addConnection(
-        userInfo: OptionalProps<UserInfo<TIO, TPresence>, "presence">,
-    ): AddConnectionResult<TIO, TPresence> {
-        /**
-         * @description Ensure that the presence is complete, so that it does not fail schema
-         * validation
-         * @date April 20, 2025
-         */
-        const cleaned = pickBy(userInfo.presence ?? {}, (value) => typeof value !== "undefined");
-        const presence = { ...this.initialPresence, ...cleaned };
-        const data: UserInfo<TIO, TPresence> = { ...userInfo, presence };
-
-        const myClientId = !!this._myself ? this.getClientId(this._myself) : null;
-        const clientId = this.getClientId(data);
-        const remaining = this._setConnectionId(userInfo.connectionId, clientId).size;
-
-        if (myClientId === clientId) {
-            const result: AddConnectionResult<TIO, TPresence> = {
-                clientId,
-                data,
-                isMyself: true,
-                remaining,
-            };
-
-            return result;
-        }
-
-        const other = this._others.get(clientId);
-
-        /**
-         * !HACK
-         * @description Don't override the other user, so that we ensure the user's presence isn't
-         * overwritten by whatever incoming connection.
-         * @date April 16, 2025
-         */
-        if (!other) this._others.set(clientId, data);
-
-        const result: AddConnectionResult<TIO, TPresence> = {
-            clientId,
-            data,
-            isMyself: false,
-            remaining,
-        };
-
-        return result;
-    }
-
-    public clearConnections(): void {
-        this.removeMyself();
-        this._others.clear();
-        this._idMap.fromClientId.clear();
-        this._idMap.fromConnectionId.clear();
-    }
-
-    public deleteConnection(connectionId: string): DeleteConnectionResult<TIO, TPresence> | null {
-        const clientId = this.getClientId(connectionId);
-
-        this._deleteConnectionId(connectionId);
-
-        // We expect that a clientId should always exist here, but we'll just check this anyways
-        if (!clientId) return null;
-
-        const userInfo = this._others.get(clientId) ?? null;
-
-        // We also expect this should always exist here, but we'll just check this anyways
-        if (!userInfo) return null;
-
-        const remaining = this._getConnectionIds(clientId)?.size ?? 0;
-        const result: DeleteConnectionResult<TIO, TPresence> = {
-            clientId,
-            remaining,
-            data: userInfo,
-        };
-
-        /**
-         * @description A user may have multiple websocket connections open. If one connection is
-         * dropped, the user may still be connected via another websocket (e.g. on anther browser
-         * tab). In this case, we just want to remove the connection mapping for the connection
-         * that is dropped, but keep the remaining connections and the user.
-         * @date April 16, 2025
-         */
-        if (!remaining) this._others.delete(clientId);
-
-        return result;
-    }
-
-    /**
-     * @description The client id is either the user's id (if authorized) or the connection id
-     * otherwise. This is so that, despite having multiple connections, the user will only have one
-     * presence to all other users.
-     * @date April 16, 2025
-     */
-    public getClientId(connectionId: string): string | null;
-    public getClientId(userInfo: UserInfo<TIO, TPresence>): string;
-    public getClientId(input: string | UserInfo<TIO, TPresence>): string | null {
-        if (typeof input !== "string") {
-            const userInfo = input;
-            const connectionId = userInfo.connectionId;
-            const userId = userInfo.user?.id ?? null;
-
-            return userId ?? connectionId;
-        }
-
-        const connectionId = input;
-
-        if (this._myself?.connectionId === connectionId) {
-            return this.getClientId(this._myself);
-        }
-
-        const clientId = this._idMap.fromConnectionId.get(connectionId) ?? null;
-
-        return clientId;
-    }
-
-    public getOther(connectionId: string): UserInfo<TIO, TPresence> | null {
-        const clientId = this.getClientId(connectionId);
-
-        if (!clientId) return null;
-
-        return this._others.get(clientId) ?? null;
-    }
-
-    public getOthers(): readonly UserInfo<TIO, TPresence>[] {
-        return Array.from(this._others.values());
-    }
-
-    public patchPresence(connectionId: string, patch: Partial<TPresence>): TPresence | null {
-        const clientId = this.getClientId(connectionId);
-        const myClientId = !!this._myself ? this.getClientId(this._myself) : null;
-
-        if (!clientId) return null;
-        if (myClientId === clientId) return this.updateMyPresence(patch);
-
-        const other = this._others.get(clientId);
-
-        if (!other) return null;
-
-        const cleanedPatch = pickBy(patch ?? {}, (value) => typeof value !== "undefined");
-        const cleanedPresence = pickBy(
-            other.presence ?? {},
-            (value) => typeof value !== "undefined",
-        );
-        const presence = {
-            ...this.initialPresence,
-            ...cleanedPresence,
-            ...cleanedPatch,
-        } as TPresence;
-        const validated = this._presence ? this._presence.parse(presence) : presence;
-
-        /**
-         * !HACK
-         * @description We're patching internal metadata back into the presence field so it doesn't
-         * get stripped from validation
-         * @date May 13, 2025
-         */
-        if (!!presence[PLUV_PRESENCE_META_KEY]) {
-            (validated as any)[PLUV_PRESENCE_META_KEY] = presence[PLUV_PRESENCE_META_KEY];
-        }
-
-        this._others.set(clientId, { ...other, presence: validated });
-
-        return validated;
-    }
-
-    public removeMyself(): void {
-        if (!this._myself) return;
-
-        const connectionId = this._myself.connectionId;
-
-        this._deleteConnectionId(connectionId);
-        this._myself = null;
-    }
-
-    public setMyself(userInfo: OptionalProps<UserInfo<TIO, TPresence>, "presence">): void {
-        const connectionId = userInfo.connectionId;
-        const presence = userInfo.presence ?? this.initialPresence;
-
-        this._myself = { ...userInfo, presence };
-        this._myPresence = presence;
-
-        const clientId = this.getClientId(this._myself);
-
-        this._setConnectionId(connectionId, clientId);
-    }
-
-    public setPresence(connectionId: string, presence: TPresence): void {
-        const clientId = this.getClientId(connectionId);
-        const myClientId = !!this._myself ? this.getClientId(this._myself) : null;
-
-        if (!clientId) return;
-
-        if (myClientId === clientId) {
-            if (!this._myself) return;
-
-            this._myself.presence = presence;
-            this._myPresence = presence;
-
-            return;
-        }
-
-        const other = this._others.get(clientId);
-
-        if (!other) return;
-
-        this._others.set(clientId, { ...other, presence });
-    }
-
-    /**
-     * @description This method need not care about being connected. This is because a user should
-     * be able to view and update their own presence without being online
-     * @date April 20, 2025
-     */
-    public updateMyPresence(patch: Partial<TPresence>): TPresence {
-        const cleanedPatch = pickBy(patch, (value) => typeof value !== "undefined");
-        const cleanedPresence = pickBy(this._myPresence, (value) => typeof value !== "undefined");
-        const updated = {
-            ...this.initialPresence,
-            ...cleanedPresence,
-            ...cleanedPatch,
-        } as TPresence;
-        const bytes = new TextEncoder().encode(JSON.stringify(updated)).length;
-
-        if (!!this._limits.presenceMaxSize && bytes > this._limits.presenceMaxSize) {
-            throw new Error(
-                `Large presence. Presence must be at most 512 bytes. Current size: ${bytes.toLocaleString()}`,
-            );
-        }
-
-        this._myPresence = updated;
-
-        if (!this._myself) return updated;
-
-        this._myself.presence = updated;
-
-        return updated;
-    }
-
-    private _deleteConnectionId(connectionId: string): void {
-        const clientId = this.getClientId(connectionId);
-
-        this._idMap.fromConnectionId.delete(connectionId);
-
-        if (!clientId) return;
-
-        const set = this._idMap.fromClientId.get(clientId) ?? null;
-
-        if (!set) return;
-
-        set.delete(connectionId);
-
-        if (!!set.size) return;
-
-        this._idMap.fromClientId.delete(clientId);
-    }
-
-    private _getConnectionIds(clientId: string): Set<[connectionId: string][0]> | null {
-        const set = this._idMap.fromClientId.get(clientId);
-
-        return set ?? null;
-    }
-
-    private _setConnectionId(
-        connectionId: string,
-        clientId: string,
-    ): Set<[connectionId: string][0]> {
-        const set = this._idMap.fromClientId.get(clientId) ?? new Set<string>();
-        const updated = set.add(connectionId);
-
-        this._idMap.fromConnectionId.set(connectionId, clientId);
-        this._idMap.fromClientId.set(clientId, updated);
-
-        return updated;
-    }
-}

package/src/UsersNotifier.ts

@@ -1,66 +0,0 @@
-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 Record<string, any> = {}> {
-    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/constants.ts

@@ -1,2 +0,0 @@
-export const MAX_PRESENCE_SIZE_BYTES = 512;
-export const PLUV_PRESENCE_META_KEY = "__pluv";

package/src/createClient.ts

@@ -1,14 +0,0 @@
-import type { InferIOCrdtKind, IOLike, JsonObject } from "@pluv/types";
-import type { PluvClientOptions } from "./PluvClient";
-import { PluvClient } from "./PluvClient";
-
-export const createClient = <
-    TIO extends IOLike<any, any, any>,
-    TPresence extends Record<string, any> = {},
-    TCrdt extends InferIOCrdtKind<TIO> = InferIOCrdtKind<TIO>,
-    TMetadata extends JsonObject = {},
->(
-    options: PluvClientOptions<TIO, TPresence, TCrdt, TMetadata>,
-): PluvClient<TIO, TPresence, TCrdt, TMetadata> => {
-    return new PluvClient<TIO, TPresence, TCrdt, TMetadata>(options);
-};

package/src/index.ts

@@ -1,36 +0,0 @@
-export type { CrdtType, InferCrdtJson } from "@pluv/crdt";
-export { ConnectionState } from "@pluv/types";
-export type {
-    BaseUser,
-    EventMessage,
-    EventNotifierSubscriptionCallback,
-    EventRecord,
-    IOEventMessage,
-    MergeEvents,
-    RoomLike,
-    UserInfo,
-    WebSocketConnection,
-    WebSocketState,
-} from "@pluv/types";
-export { AbstractStorageStore } from "./AbstractStorageStore";
-export { createClient } from "./createClient";
-export { infer } from "./infer";
-export type { InferCallback } from "./infer";
-export { MockedRoom } from "./MockedRoom";
-export type { MockedRoomConfig, MockedRoomEvents } from "./MockedRoom";
-export { PluvClient } from "./PluvClient";
-export type { CreateRoomOptions, EnterRoomParams, PluvClientOptions } from "./PluvClient";
-export type { PluvProcedureConfig } from "./PluvProcedure";
-export { PluvRoom } from "./PluvRoom";
-export type {
-    PluvRoomAddon,
-    PluvRoomAddonInput,
-    PluvRoomAddonResult,
-    PluvRoomDebug,
-    RoomConnectParams,
-    RoomEndpoints,
-} from "./PluvRoom";
-export type { PluvRouter, PluvRouterEventConfig } from "./PluvRouter";
-export { register } from "./register";
-export type { RegisterParams } from "./register";
-export type { InferMetadata, PublicKey, PublicKeyParams } from "./types";

package/src/infer.ts

@@ -1,12 +0,0 @@
-import type { InferIOAuthorize, InferIOCrdt, InferIOEvents, IOLike } from "@pluv/types";
-import type { identity } from "./utils";
-
-export type InferCallback<TIO extends IOLike<any, any, any>> = (i: typeof identity) => {
-    io: (io: TIO) => TIO;
-};
-
-export const infer = <TIO extends IOLike<any, any, any>>(
-    callback: InferCallback<TIO>,
-): InferCallback<IOLike<InferIOAuthorize<TIO>, InferIOCrdt<TIO>, InferIOEvents<TIO>>> => {
-    return callback as any;
-};

package/src/register.ts

@@ -1,20 +0,0 @@
-import type { JsonObject } from "@pluv/types";
-import type { AuthEndpoint, WsEndpoint } from "./PluvRoom";
-
-export interface RegisterParams<TMetadata extends JsonObject> {
-    authEndpoint: AuthEndpoint<TMetadata>;
-    publicKey: string;
-}
-
-export const register = <TMetadata extends JsonObject>(params: RegisterParams<TMetadata>) => {
-    const { authEndpoint, publicKey } = params;
-
-    const wsEndpoint: WsEndpoint<TMetadata> = ({ room }) =>
-        `wss://connect.pluv.io/api/room?room=${room}`;
-
-    return {
-        authEndpoint,
-        publicKey,
-        wsEndpoint,
-    };
-};