@pluv/react 0.0.0-experimental-20250527040415

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2022 Shoubhit Dash
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,18 @@
+## `@pluv/react`
+
+> [React.js](https://reactjs.org/) bindings for [@pluv/client](https://www.npmjs.com/package/@pluv/client).
+
+**👉 See full documentation on [pluv.io](https://pluv.io/docs/introduction). 👈**
+
+## Installation
+
+```bash
+# npm
+npm install @pluv/client @pluv/react @pluv/crdt-yjs yjs zod
+
+# yarn
+yarn add @pluv/client @pluv/react @pluv/crdt-yjs yjs zod
+
+# pnpm
+pnpm add @pluv/client @pluv/react @pluv/crdt-yjs yjs zod
+```

package/dist/index.d.mts

@@ -0,0 +1,72 @@
+import { PluvRouterEventConfig, MockedRoomEvents, MergeEvents, PluvRoomDebug, PluvClient, WebSocketConnection, UserInfo, PluvRoomAddon, PluvRouter } from '@pluv/client';
+import { AbstractCrdtDocFactory, NoopCrdtDocFactory, InferStorage, InferInitialStorageFn, InferDoc, InferCrdtJson } from '@pluv/crdt';
+import { IOLike, JsonObject, MaybePromise, InferIOOutput, Id, IOEventMessage, InferIOInput, CrdtDocLike, UpdateMyPresenceAction, RoomLike } from '@pluv/types';
+import { FC, ReactNode, Dispatch } from 'react';
+
+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;
+});
+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>>;
+};
+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;
+};
+type EventProxy<TIO extends IOLike> = {
+    [event in keyof InferIOOutput<TIO>]: {
+        useEvent: (callback: (data: Id<IOEventMessage<TIO, event>>) => void) => void;
+    };
+};
+type MetadataGetter<TMetadata extends JsonObject> = TMetadata | (() => MaybePromise<TMetadata>);
+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>;
+});
+interface SubscriptionHookOptions<T extends unknown> {
+    isEqual?: (a: T, b: T) => boolean;
+}
+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>> = {}> {
+    MockedRoomProvider: FC<MockedRoomProviderProps<TIO, TPresence, TCrdt>>;
+    PluvProvider: FC<PluvProviderProps>;
+    PluvRoomProvider: FC<PluvRoomProviderProps<TIO, TMetadata, TPresence, TCrdt>>;
+    event: EventProxy<MergeEvents<TEvents, TIO>>;
+    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;
+}
+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;
+
+type CreateBundleOptions<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>> = {}> = {
+    addons?: readonly PluvRoomAddon<TIO, TMetadata, TPresence, TCrdt>[];
+    router?: PluvRouter<TIO, TPresence, InferStorage<TCrdt>, TEvents>;
+};
+declare const createBundle: <TIO extends IOLike<any, any>, TMetadata extends JsonObject = {}, TPresence extends Record<string, any> = {}, TCrdt extends AbstractCrdtDocFactory<any, any> = NoopCrdtDocFactory, TEvents extends PluvRouterEventConfig<TIO, TPresence, InferStorage<TCrdt>> = {}>(client: PluvClient<TIO, TPresence, TCrdt, TMetadata>, options?: CreateBundleOptions<TIO, TMetadata, TPresence, TCrdt, TEvents>) => CreateBundle<TIO, TMetadata, TPresence, TCrdt, TEvents>;
+
+export { type CreateBundle, type EventProxy, type InferBundleRoom, type PluvProviderProps, type PluvRoomProviderProps, type SubscriptionHookOptions, createBundle };

package/dist/index.d.ts

@@ -0,0 +1,72 @@
+import { PluvRouterEventConfig, MockedRoomEvents, MergeEvents, PluvRoomDebug, PluvClient, WebSocketConnection, UserInfo, PluvRoomAddon, PluvRouter } from '@pluv/client';
+import { AbstractCrdtDocFactory, NoopCrdtDocFactory, InferStorage, InferInitialStorageFn, InferDoc, InferCrdtJson } from '@pluv/crdt';
+import { IOLike, JsonObject, MaybePromise, InferIOOutput, Id, IOEventMessage, InferIOInput, CrdtDocLike, UpdateMyPresenceAction, RoomLike } from '@pluv/types';
+import { FC, ReactNode, Dispatch } from 'react';
+
+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;
+});
+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>>;
+};
+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;
+};
+type EventProxy<TIO extends IOLike> = {
+    [event in keyof InferIOOutput<TIO>]: {
+        useEvent: (callback: (data: Id<IOEventMessage<TIO, event>>) => void) => void;
+    };
+};
+type MetadataGetter<TMetadata extends JsonObject> = TMetadata | (() => MaybePromise<TMetadata>);
+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>;
+});
+interface SubscriptionHookOptions<T extends unknown> {
+    isEqual?: (a: T, b: T) => boolean;
+}
+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>> = {}> {
+    MockedRoomProvider: FC<MockedRoomProviderProps<TIO, TPresence, TCrdt>>;
+    PluvProvider: FC<PluvProviderProps>;
+    PluvRoomProvider: FC<PluvRoomProviderProps<TIO, TMetadata, TPresence, TCrdt>>;
+    event: EventProxy<MergeEvents<TEvents, TIO>>;
+    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;
+}
+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;
+
+type CreateBundleOptions<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>> = {}> = {
+    addons?: readonly PluvRoomAddon<TIO, TMetadata, TPresence, TCrdt>[];
+    router?: PluvRouter<TIO, TPresence, InferStorage<TCrdt>, TEvents>;
+};
+declare const createBundle: <TIO extends IOLike<any, any>, TMetadata extends JsonObject = {}, TPresence extends Record<string, any> = {}, TCrdt extends AbstractCrdtDocFactory<any, any> = NoopCrdtDocFactory, TEvents extends PluvRouterEventConfig<TIO, TPresence, InferStorage<TCrdt>> = {}>(client: PluvClient<TIO, TPresence, TCrdt, TMetadata>, options?: CreateBundleOptions<TIO, TMetadata, TPresence, TCrdt, TEvents>) => CreateBundle<TIO, TMetadata, TPresence, TCrdt, TEvents>;
+
+export { type CreateBundle, type EventProxy, type InferBundleRoom, type PluvProviderProps, type PluvRoomProviderProps, type SubscriptionHookOptions, createBundle };