@pluv/react 0.0.0-experimental-20250527040415

package/src/internal/hooks/useDeepAsyncMemo.ts

@@ -0,0 +1,120 @@
+import { useEffect, useRef, useState } from "react";
+import fastDeepEqual from "fast-deep-equal";
+
+export type UseDeepAsyncMemoResult<T extends unknown> =
+    | {
+          error: null;
+          isInitialized: true;
+          isLoading: false;
+          value: T;
+      }
+    | {
+          error: null;
+          isInitialized: boolean;
+          value: undefined;
+          isLoading: true;
+      }
+    | {
+          error: Error;
+          isInitialized: boolean;
+          value: undefined;
+          isLoading: false;
+      };
+
+export const useDeepAsyncMemo = <T>(
+    factory: () => Promise<T>,
+    isEqual: (a: T, b: T) => boolean = fastDeepEqual,
+): UseDeepAsyncMemoResult<T> => {
+    // Store the current async state (loading, value, error, etc.)
+    const [state, setState] = useState<UseDeepAsyncMemoResult<T>>({
+        isInitialized: false,
+        isLoading: true,
+        value: undefined,
+        error: null,
+    });
+
+    // Keep track of the last resolved value to compare with new ones
+    const lastValueRef = useRef<T | undefined>(undefined);
+    const hasValueRef = useRef(false); // Tracks whether we've ever resolved a value
+
+    // Tracks the current in-flight promise to guard against race conditions
+    const inflightRef = useRef<Promise<T> | null>(null);
+
+    // Used to prevent state updates after the component unmounts
+    const isMountedRef = useRef(true);
+
+    useEffect(() => {
+        isMountedRef.current = true;
+
+        // Trigger the async factory
+        const promise = factory();
+        inflightRef.current = promise;
+
+        // Set loading state
+        setState((prev) => {
+            return {
+                ...prev,
+                isLoading: true,
+                error: null,
+            } as UseDeepAsyncMemoResult<T>;
+        });
+
+        promise
+            .then((result) => {
+                // Ignore if component unmounted or if this promise is stale
+                if (!isMountedRef.current || inflightRef.current !== promise) return;
+
+                // Skip update if value hasn't changed
+                const isSame = hasValueRef.current && isEqual(lastValueRef.current as T, result);
+                if (isSame) {
+                    setState((prev) => {
+                        return {
+                            ...prev,
+                            isInitialized: true,
+                            isLoading: false,
+                        } as UseDeepAsyncMemoResult<T>;
+                    });
+                    return;
+                }
+
+                // Save the new value
+                lastValueRef.current = result;
+                hasValueRef.current = true;
+
+                setState({
+                    isInitialized: true,
+                    isLoading: false,
+                    value: result,
+                    error: null,
+                });
+            })
+            .catch((err) => {
+                // Ignore if component unmounted or if this promise is stale
+                if (!isMountedRef.current || inflightRef.current !== promise) return;
+
+                setState({
+                    isInitialized: hasValueRef.current,
+                    isLoading: false,
+                    value: undefined,
+                    error: err instanceof Error ? err : new Error("Unknown error"),
+                });
+            });
+
+        // Cleanup: prevent state updates after unmount
+        return () => {
+            isMountedRef.current = false;
+        };
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [
+        /**
+         * !HACK
+         * @description We're only going to use the `isEqual` function to determine if this hook
+         * should re-run. This is basically our hook's version of a dependency array
+         * @date April 13, 2025
+         */
+        // factory,
+        isEqual,
+    ]);
+
+    return state;
+};

package/src/internal/hooks/useNoSsr.ts

@@ -0,0 +1,22 @@
+import { useCallback, useEffect, useState } from "react";
+
+export type NoSsrFunction = <T = null>(value: T | (() => T), fallback?: T) => T;
+
+export const useNoSsr = (): NoSsrFunction => {
+    const [didMount, setDidMount] = useState<boolean>(false);
+
+    useEffect(() => setDidMount(typeof window !== "undefined"), []);
+
+    const noSsr = useCallback(
+        <T = null>(value: T | (() => T), fallback: T = null as T): T => {
+            return didMount
+                ? typeof value !== "function"
+                    ? value
+                    : (value as () => T)()
+                : fallback;
+        },
+        [didMount],
+    );
+
+    return noSsr;
+};

package/src/internal/hooks/useRerender.ts

@@ -0,0 +1,9 @@
+import { useCallback, useState } from "react";
+
+export const useRerender = (): (() => void) => {
+    const [, setCount] = useState(0);
+
+    return useCallback(() => {
+        setCount((oldCount) => (oldCount + 1) % Number.MAX_SAFE_INTEGER);
+    }, []);
+};

package/src/internal/hooks/useSyncExternalStoreWithSelector.ts

@@ -0,0 +1,56 @@
+import { useRef, useSyncExternalStore } from "react";
+import { shallowEqual } from "../utils";
+import { useNoSsr } from "./useNoSsr";
+
+export const useSyncExternalStoreWithSelector = <TSnapshot, TSelection>(
+    subscribe: (onStoreChange: () => void) => () => void,
+    getClientSnapshot: () => TSnapshot,
+    getServerSnapshot: undefined | null | (() => TSnapshot),
+    selector: (snapshot: TSnapshot) => TSelection,
+    isEqual?: (a: TSelection, b: TSelection) => boolean,
+): TSelection => {
+    const noSsr = useNoSsr();
+    const cacheRef = useRef<TSelection | null>(null);
+
+    const _getServerSnapshot = getServerSnapshot
+        ? () => {
+              const data = getServerSnapshot();
+              const snapshot = selector(data);
+              const compare = isEqual ?? shallowEqual;
+              const cached = cacheRef.current;
+
+              const isUnchanged = cached === null ? snapshot === null : compare(cached, snapshot);
+
+              /**
+               * !HACK
+               * @description Memoize only the last snapshot so that we can only rerender on changes
+               * @date June 22, 2024
+               */
+              cacheRef.current = isUnchanged ? (cached ?? snapshot) : snapshot;
+
+              return cacheRef.current;
+          }
+        : undefined;
+
+    const _getClientSnapshot = () => {
+        const data = getClientSnapshot();
+        const snapshot = selector(data);
+        const compare = isEqual ?? shallowEqual;
+        const cached = cacheRef.current;
+
+        const isUnchanged = cached === null ? snapshot === null : compare(cached, snapshot);
+
+        /**
+         * !HACK
+         * @description Memoize only the last snapshot so that we can only rerender on changes
+         * @date June 22, 2024
+         */
+        cacheRef.current = isUnchanged ? (cached ?? snapshot) : snapshot;
+
+        return cacheRef.current;
+    };
+
+    const result = useSyncExternalStore(subscribe, _getClientSnapshot, _getServerSnapshot);
+
+    return typeof window !== "undefined" ? noSsr(result, _getServerSnapshot?.()) : result;
+};

package/src/internal/index.ts

@@ -0,0 +1,7 @@
+export {
+    useAsyncQueue,
+    useDeepAsyncMemo,
+    useRerender,
+    useSyncExternalStoreWithSelector,
+} from "./hooks";
+export { identity, shallowArrayEqual } from "./utils";

package/src/internal/utils/identity.ts

@@ -0,0 +1 @@
+export const identity = <T extends unknown>(x: T): T => x;

package/src/internal/utils/index.ts

@@ -0,0 +1,3 @@
+export { identity } from "./identity";
+export { shallowArrayEqual } from "./shallowArrayEqual";
+export { shallowEqual } from "./shallowEqual";

package/src/internal/utils/shallowArrayEqual.ts

@@ -0,0 +1,6 @@
+export const shallowArrayEqual = <T extends unknown>(
+    a: readonly T[] | T[],
+    b: readonly T[] | T[],
+): boolean => {
+    return a.length === b.length && a.every((item, i) => item === b[i]);
+};

package/src/internal/utils/shallowEqual.ts

@@ -0,0 +1 @@
+export const shallowEqual = (a: any, b: any): boolean => a === b;

package/src/types.ts

@@ -0,0 +1,151 @@
+import type {
+    MergeEvents,
+    MockedRoomEvents,
+    PluvClient,
+    PluvRoomDebug,
+    PluvRouterEventConfig,
+    UserInfo,
+    WebSocketConnection,
+} from "@pluv/client";
+import type {
+    AbstractCrdtDocFactory,
+    InferCrdtJson,
+    InferDoc,
+    InferInitialStorageFn,
+    InferStorage,
+    NoopCrdtDocFactory,
+} from "@pluv/crdt";
+import type {
+    CrdtDocLike,
+    Id,
+    InferIOInput,
+    InferIOOutput,
+    IOEventMessage,
+    IOLike,
+    JsonObject,
+    MaybePromise,
+    RoomLike,
+    UpdateMyPresenceAction,
+} from "@pluv/types";
+import type { Dispatch, FC, ReactNode } from "react";
+
+export interface PluvProviderProps {
+    children?: ReactNode;
+}
+
+type BaseRoomProviderProps<
+    TPresence extends Record<string, any>,
+    TCrdt extends AbstractCrdtDocFactory<any, any>,
+> = {
+    children?: ReactNode;
+    initialStorage?: keyof InferStorage<TCrdt> extends never ? never : InferInitialStorageFn<TCrdt>;
+    room: string;
+} & (keyof TPresence extends never ? { initialPresence?: never } : { initialPresence: TPresence });
+
+export type MockedRoomProviderProps<
+    TIO extends IOLike,
+    TPresence extends Record<string, any>,
+    TCrdt extends AbstractCrdtDocFactory<any, any>,
+    TEvents extends PluvRouterEventConfig<TIO, TPresence, InferStorage<TCrdt>> = {},
+> = BaseRoomProviderProps<TPresence, TCrdt> & {
+    events?: MockedRoomEvents<MergeEvents<TEvents, TIO>>;
+};
+
+export type BroadcastProxy<TIO extends IOLike> = (<TEvent extends keyof InferIOInput<TIO>>(
+    event: TEvent,
+    data: Id<InferIOInput<TIO>[TEvent]>,
+) => void) & {
+    [event in keyof InferIOInput<TIO>]: (input: Id<InferIOInput<TIO>[event]>) => void;
+};
+
+export type EventProxy<TIO extends IOLike> = {
+    [event in keyof InferIOOutput<TIO>]: {
+        useEvent: (callback: (data: Id<IOEventMessage<TIO, event>>) => void) => void;
+    };
+};
+
+export type MetadataGetter<TMetadata extends JsonObject> =
+    | TMetadata
+    | (() => MaybePromise<TMetadata>);
+
+export type PluvRoomProviderProps<
+    TIO extends IOLike<any, any>,
+    TMetadata extends JsonObject,
+    TPresence extends Record<string, any>,
+    TCrdt extends AbstractCrdtDocFactory<any, any>,
+> = BaseRoomProviderProps<TPresence, TCrdt> & {
+    connect?: boolean;
+    debug?: boolean | PluvRoomDebug<TIO>;
+    onAuthorizationFail?: (error: Error) => void;
+} & (keyof TMetadata extends never
+        ? { metadata?: undefined }
+        : { metadata: MetadataGetter<TMetadata> });
+
+export interface SubscriptionHookOptions<T extends unknown> {
+    isEqual?: (a: T, b: T) => boolean;
+}
+
+export interface CreateBundle<
+    TIO extends IOLike<any>,
+    TMetadata extends JsonObject,
+    TPresence extends Record<string, any> = {},
+    TCrdt extends AbstractCrdtDocFactory<any, any> = NoopCrdtDocFactory,
+    TEvents extends PluvRouterEventConfig<TIO, TPresence, InferStorage<TCrdt>> = {},
+> {
+    // components
+    MockedRoomProvider: FC<MockedRoomProviderProps<TIO, TPresence, TCrdt>>;
+    PluvProvider: FC<PluvProviderProps>;
+    PluvRoomProvider: FC<PluvRoomProviderProps<TIO, TMetadata, TPresence, TCrdt>>;
+
+    // proxies
+    event: EventProxy<MergeEvents<TEvents, TIO>>;
+
+    // hooks
+    useBroadcast: () => BroadcastProxy<MergeEvents<TEvents, TIO>>;
+    useCanRedo: () => boolean;
+    useCanUndo: () => boolean;
+    useClient: () => PluvClient<TIO, TPresence, TCrdt, TMetadata>;
+    useConnection: <T extends unknown = WebSocketConnection>(
+        selector?: (connection: WebSocketConnection) => T,
+        options?: SubscriptionHookOptions<Id<T>>,
+    ) => Id<T>;
+    useDoc: () => CrdtDocLike<InferDoc<TCrdt>, InferStorage<TCrdt>>;
+    useEvent: <TType extends keyof InferIOOutput<MergeEvents<TEvents, TIO>>>(
+        type: TType,
+        callback: (data: Id<IOEventMessage<MergeEvents<TEvents, TIO>, TType>>) => void,
+    ) => void;
+    useMyPresence: <T extends unknown = TPresence>(
+        selector?: (myPresence: TPresence) => T,
+        options?: SubscriptionHookOptions<Id<T> | null>,
+    ) => [myPresence: Id<T>, updateMyPresence: Dispatch<UpdateMyPresenceAction<TPresence>>];
+    useMyself: <T extends unknown = UserInfo<TIO, TPresence>>(
+        selector?: (myself: Id<UserInfo<TIO, TPresence>>) => T,
+        options?: SubscriptionHookOptions<Id<T> | null>,
+    ) => Id<T> | null;
+    useOther: <T extends unknown = UserInfo<TIO, TPresence>>(
+        connectionId: string,
+        selector?: (other: UserInfo<TIO, TPresence>) => T,
+        options?: SubscriptionHookOptions<T | null>,
+    ) => T | null;
+    useOthers: <T extends unknown = readonly UserInfo<TIO, TPresence>[]>(
+        selector?: (other: readonly Id<UserInfo<TIO, TPresence>>[]) => T,
+        options?: SubscriptionHookOptions<T>,
+    ) => T;
+    useRedo: () => () => void;
+    useRoom: () => RoomLike<TIO, InferDoc<TCrdt>, TPresence, InferStorage<TCrdt>, TEvents>;
+    useStorage: <
+        TKey extends keyof InferStorage<TCrdt>,
+        TData extends unknown = InferCrdtJson<InferStorage<TCrdt>[TKey]>,
+    >(
+        key: TKey,
+        selector?: (data: InferCrdtJson<InferStorage<TCrdt>[TKey]>) => TData,
+        options?: SubscriptionHookOptions<TData | null>,
+    ) => [data: TData | null, sharedType: InferStorage<TCrdt>[TKey] | null];
+    useTransact: () => (fn: (storage: InferStorage<TCrdt>) => void, origin?: string) => void;
+    useUndo: () => () => void;
+}
+
+export type InferBundleRoom<TBundle extends CreateBundle<any, any, any, any, any>> =
+    TBundle extends CreateBundle<infer IIO, any, infer IPresence, infer ICrdt, infer IEvents>
+        ? RoomLike<IIO, InferDoc<ICrdt>, IPresence, InferStorage<ICrdt>, IEvents>
+        : never;

package/tsconfig.json

@@ -0,0 +1,8 @@
+{
+	"extends": "@pluv/tsconfig/react-library.json",
+	"include": ["next-env.d.ts", "**/*.ts", "**/*.tsx"],
+	"exclude": ["node_modules"],
+	"compilerOptions": {
+		"lib": ["dom", "esnext"]
+	}
+}