@pluv/react 0.25.4 → 0.27.0

package/.turbo/turbo-build.log

@@ -1,18 +1,18 @@
 
-> @pluv/react@0.25.4 build /home/runner/work/pluv/pluv/packages/react
+> @pluv/react@0.27.0 build /home/runner/work/pluv/pluv/packages/react
 > tsup src/index.ts --format esm,cjs --dts --external react
 
 CLI Building entry: src/index.ts
 CLI Using tsconfig: tsconfig.json
-CLI tsup v8.2.4
+CLI tsup v8.3.0
 CLI Target: es6
 ESM Build start
 CJS Build start
-ESM dist/index.mjs 11.87 KB
-ESM ⚡️ Build success in 124ms
-CJS dist/index.js 14.27 KB
-CJS ⚡️ Build success in 125ms
+CJS dist/index.js 14.26 KB
+CJS ⚡️ Build success in 101ms
+ESM dist/index.mjs 11.85 KB
+ESM ⚡️ Build success in 102ms
 DTS Build start
-DTS ⚡️ Build success in 4984ms
-DTS dist/index.d.mts 5.17 KB
-DTS dist/index.d.ts  5.17 KB
+DTS ⚡️ Build success in 5825ms
+DTS dist/index.d.mts 6.12 KB
+DTS dist/index.d.ts  6.12 KB

package/CHANGELOG.md

@@ -1,5 +1,181 @@
 # @pluv/react
 
+## 0.27.0
+
+### Minor Changes
+
+- 19ed36c: Updated `createClient` and `createRoomBundle` object params to better support automatic type inference.
+
+  ```ts
+  // Before
+  import { createClient } from "@pluv/react";
+  import { yjs } from "@pluv/crdt-yjs";
+  import { z } from "zod";
+  import type { ioServer } from "./server/ioServer";
+
+  const client = createClient<typeof ioServer>({
+    authEndpoint: ({ room }) => "MY_AUTH_URL",
+    wsEndpoint: ({ room }) => "MY_WEBSOCKET_URL",
+  });
+
+  client.createRoom("my-example-room", {
+    presence: z.object({
+      selectionId: z.string().nullish(),
+    }),
+    initialPresence: {
+      selectionId: null,
+    },
+    initialStorage: yjs.doc(() => ({
+      messages: yjs.array<string>([]),
+    })),
+  });
+
+  // After
+
+  import { createBundle, createClient } from "@pluv/react";
+
+  const client = createClient({
+    authEndpoint: ({ room }) => "MY_AUTH_URL",
+    wsEndpoint: ({ room }) => "MY_WEBSOCKET_URL",
+    /**
+     * @description The ioServer type now needs to be inferred on this property
+     * instead of within the generic on `createClient`. This is because of
+     * limitations with TypeScript not yet supporting partial type-inference
+     * for generics. Ensure to no-loonger include any generics on `createClient`
+     */
+    infer: (i) => ({ io: i<typeof ioServer> }),
+    // Now moved to `createClient` from `PluvClient.createRoom`
+    presence: z.object({
+      selectionId: z.string().nullish(),
+    }),
+    /**
+     * @description Now added to `createClient` to specify defaults for all
+     * rooms, and to infer types for storage. This value will be overwritten by
+     * `PluvClient.createRoom`.
+     */
+    initialStorage: yjs.doc(() => ({
+      messages: yjs.array<string>([]),
+    })),
+  });
+
+  const { createRoomBundle } = createBundle(client);
+  const pluv = createRoomBundle({});
+  ```
+
+### Patch Changes
+
+- 19ed36c: Added client-side event router. This more-or-less mirrors the server-side event router. You can use both the server-side and client-side router simultaneously, but you should generally prefer only using one or the other.
+
+  ```ts
+  // Backend Server
+  import { createIO } from "@pluv/io";
+
+  const io = createIO({ /* ... */ });
+  const ioServer = io.server({
+      router: io.router({
+          multiply2: io.procedure
+              .input(z.object({ value: z.number() }))
+              .broadcast(({ value }) => ({
+                  multiplied2: { value: value * 2 },
+              })),
+      }),
+  });
+
+  // Frontend Client
+  import { createBundle createClient } from "@pluv/react";
+
+  const io = createClient({ /* ... */ });
+
+  const { createRoomBundle } = createBundle(io);
+  const pluv = createRoomBundle({
+      // ...
+      router: io.router({
+          add5: io.procedure
+              .input(z.object({ value: z.number() }))
+              .broadcast(({ value }) => ({
+                  /**
+                   * @description Because `ioServer` does not specify `added5`,
+                   * this will be forwarded to connected peers.
+                   */
+                  added5: { value: value + 5 },
+              })),
+          /**
+           * @description This is possible, but not recommended to do. Because
+           * `multiply2` is a procedure on `ioServer`, this will trigger the
+           * `multiply2` procedure on `ioServer`. Connected peers will not
+           * receive `multiply2`, but rather `multipled2`.
+           */
+          subtract5Multiply2: io.procedure
+              .input(z.object({ value: z.number() }))
+              .broadcast(({ value }) => ({
+                  multiply2: { value: value - 5 },
+              })),
+      }),
+  });
+  ```
+
+- Updated dependencies [19ed36c]
+- Updated dependencies [19ed36c]
+  - @pluv/client@0.27.0
+  - @pluv/crdt@0.27.0
+  - @pluv/types@0.27.0
+
+## 0.26.0
+
+### Minor Changes
+
+- 19e5dda: **BREAKING**
+  Update `authEndpoint` and `wsEndpoint` to now use a parameterized object that passes through additional data via a `metadata` property.
+
+  ```tsx
+  // Before
+
+  import { env } from "./env";
+  import type { ioServer } from "./server";
+
+  const client = createClient<typeof ioServer>({
+      authEndpoint: (room: string) => `${env.API_URL}}/room/${room}`,
+      wsEndpoint: (room: string) => `${env.WS_URL}/room/${room}`,
+  });
+
+  // After
+
+  const client = createClient<
+      typeof ioServer,
+      // Optional: You can specify types for metadata here. This is useful for Cloudflare Pages
+      { apiUrl: string; wsUrl: string }
+  >({
+      authEndpoint: ({ metadata, room }) => `${metadata.apiUrl}}/room/${room}`,
+      wsEndpoint: ({ metadata, room }) => `${{ metadata.wsUrl }}/room/${room}`,
+  });
+
+  client.createRoom("my-room", {
+      // This property exists when the `metadata` generic type is defined above
+      metadata: {
+          apiUrl: "https://example.com/api",
+          wsUrl: "wss://example.com/api",
+      },
+      // ...
+  });
+
+  <PluvRoomProvider
+      // This property exists when the `metadata` generic type is defined above
+      metadata={{
+          apiUrl: "https://example.com/api",
+          wsUrl: "wss://example.com/api",
+      }}
+  >
+      {/* ... */}
+  </PluvRoomProvider>
+  ```
+
+### Patch Changes
+
+- Updated dependencies [19e5dda]
+  - @pluv/client@0.26.0
+  - @pluv/crdt@0.26.0
+  - @pluv/types@0.26.0
+
 ## 0.25.4
 
 ### Patch Changes

package/dist/index.d.mts

@@ -1,15 +1,15 @@
-import { PluvRoomAddon, PluvRoomDebug, WebSocketConnection, UserInfo, AbstractRoom, MockedRoomEvents, PluvClient } from '@pluv/client';
+import { PluvRouterEventConfig, PluvRoomAddon, PluvRouter, PluvRoomDebug, MergeEvents, WebSocketConnection, UserInfo, AbstractRoom, MockedRoomEvents, PluvClient } from '@pluv/client';
 export { ConnectionState, createClient } from '@pluv/client';
 import { CrdtType, AbstractCrdtDocFactory, AbstractCrdtDoc, InferCrdtJson } from '@pluv/crdt';
 export { CrdtType, InferCrdtJson } from '@pluv/crdt';
-import { IOLike, JsonObject, InputZodLike, Id, InferIOOutput, IOEventMessage, InferIOInput } from '@pluv/types';
+import { IOLike, JsonObject, Id, InferIOOutput, IOEventMessage, InferIOInput } from '@pluv/types';
 export { BaseUser, EventMessage, EventRecord, IOEventMessage } from '@pluv/types';
 import { FC, Dispatch, ReactNode } from 'react';
 
-type CreateRoomBundleOptions<TIO extends IOLike, TPresence extends JsonObject = {}, TStorage extends Record<string, CrdtType<any, any>> = {}> = {
-    addons?: readonly PluvRoomAddon<TIO, TPresence, TStorage>[];
+type CreateRoomBundleOptions<TIO extends IOLike, TMetadata extends JsonObject = {}, TPresence extends JsonObject = {}, TStorage extends Record<string, CrdtType<any, any>> = {}, TEvents extends PluvRouterEventConfig<TIO, TPresence, TStorage> = {}> = {
+    addons?: readonly PluvRoomAddon<TIO, TMetadata, TPresence, TStorage>[];
     initialStorage?: AbstractCrdtDocFactory<TStorage>;
-    presence?: InputZodLike<TPresence>;
+    router?: PluvRouter<TIO, TPresence, TStorage, TEvents>;
 };
 type BaseRoomProviderProps<TPresence extends JsonObject, TStorage extends Record<string, CrdtType<any, any>>> = {
     children?: ReactNode;
@@ -20,13 +20,17 @@ type BaseRoomProviderProps<TPresence extends JsonObject, TStorage extends Record
 } : {
     initialPresence: TPresence;
 });
-type MockedRoomProviderProps<TIO extends IOLike, TPresence extends JsonObject, TStorage extends Record<string, CrdtType<any, any>>> = BaseRoomProviderProps<TPresence, TStorage> & {
-    events?: MockedRoomEvents<TIO>;
+type MockedRoomProviderProps<TIO extends IOLike, TPresence extends JsonObject, TStorage extends Record<string, CrdtType<any, any>>, TEvents extends PluvRouterEventConfig<TIO, TPresence, TStorage> = {}> = BaseRoomProviderProps<TPresence, TStorage> & {
+    events?: MockedRoomEvents<MergeEvents<TEvents, TIO>>;
 };
-type PluvRoomProviderProps<TIO extends IOLike, TPresence extends JsonObject, TStorage extends Record<string, CrdtType<any, any>>> = BaseRoomProviderProps<TPresence, TStorage> & {
+type PluvRoomProviderProps<TIO extends IOLike, TMetadata extends JsonObject, TPresence extends JsonObject, TStorage extends Record<string, CrdtType<any, any>>> = BaseRoomProviderProps<TPresence, TStorage> & {
     debug?: boolean | PluvRoomDebug<TIO>;
     onAuthorizationFail?: (error: Error) => void;
-};
+} & (keyof TMetadata extends never ? {
+    metadata?: undefined;
+} : {
+    metadata: TMetadata;
+});
 interface SubscriptionHookOptions<T extends unknown> {
     isEqual?: (a: T, b: T) => boolean;
 }
@@ -39,16 +43,16 @@ type EventProxy<TIO extends IOLike> = {
         useEvent: (callback: (data: Id<IOEventMessage<TIO, event>>) => void) => void;
     };
 };
-interface CreateRoomBundle<TIO extends IOLike, TPresence extends JsonObject, TStorage extends Record<string, CrdtType<any, any>>> {
+interface CreateRoomBundle<TIO extends IOLike, TMetadata extends JsonObject, TPresence extends JsonObject, TStorage extends Record<string, CrdtType<any, any>>, TEvents extends PluvRouterEventConfig<TIO, TPresence, TStorage> = {}> {
     MockedRoomProvider: FC<MockedRoomProviderProps<TIO, TPresence, TStorage>>;
-    PluvRoomProvider: FC<PluvRoomProviderProps<TIO, TPresence, TStorage>>;
-    event: EventProxy<TIO>;
-    useBroadcast: () => BroadcastProxy<TIO>;
+    PluvRoomProvider: FC<PluvRoomProviderProps<TIO, TMetadata, TPresence, TStorage>>;
+    event: EventProxy<MergeEvents<TEvents, TIO>>;
+    useBroadcast: () => BroadcastProxy<MergeEvents<TEvents, TIO>>;
     useCanRedo: () => boolean;
     useCanUndo: () => boolean;
     useConnection: <T extends unknown = WebSocketConnection>(selector: (connection: WebSocketConnection) => T, options?: SubscriptionHookOptions<Id<T>>) => Id<T>;
     useDoc: () => AbstractCrdtDoc<TStorage>;
-    useEvent: <TType extends keyof InferIOOutput<TIO>>(type: TType, callback: (data: Id<IOEventMessage<TIO, TType>>) => void) => void;
+    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;
@@ -59,16 +63,16 @@ interface CreateRoomBundle<TIO extends IOLike, TPresence extends JsonObject, TSt
     useTransact: () => (fn: (storage: TStorage) => void, origin?: string) => void;
     useUndo: () => () => void;
 }
-type InferRoomStorage<TRoomBundle extends CreateRoomBundle<any, any, any>> = TRoomBundle extends CreateRoomBundle<any, any, infer IStorage> ? IStorage : never;
+type InferRoomStorage<TRoomBundle extends CreateRoomBundle<any, any, any, any, any>> = TRoomBundle extends CreateRoomBundle<any, any, any, infer IStorage> ? IStorage : never;
 
 interface PluvProviderProps {
     children?: ReactNode;
 }
-interface CreateBundle<TIO extends IOLike> {
-    createRoomBundle: <TPresence extends JsonObject = {}, TStorage extends Record<string, CrdtType<any, any>> = {}>(options: CreateRoomBundleOptions<TIO, TPresence, TStorage>) => CreateRoomBundle<TIO, TPresence, TStorage>;
+interface CreateBundle<TIO extends IOLike, TMetadata extends JsonObject, TPresence extends JsonObject = {}, TStorage extends Record<string, CrdtType<any, any>> = {}> {
+    createRoomBundle: <TEvents extends PluvRouterEventConfig<TIO, TPresence, TStorage> = {}>(options: CreateRoomBundleOptions<TIO, TMetadata, TPresence, TStorage, TEvents>) => CreateRoomBundle<TIO, TMetadata, TPresence, TStorage, TEvents>;
     PluvProvider: FC<PluvProviderProps>;
-    useClient: () => PluvClient<TIO>;
+    useClient: () => PluvClient<TIO, TPresence, TStorage, TMetadata>;
 }
-declare const createBundle: <TIO extends IOLike>(client: PluvClient<TIO>) => CreateBundle<TIO>;
+declare const createBundle: <TIO extends IOLike, TMetadata extends JsonObject = {}, TPresence extends JsonObject = {}, TStorage extends Record<string, CrdtType<any, any>> = {}>(client: PluvClient<TIO, TPresence, TStorage, TMetadata>) => CreateBundle<TIO, TMetadata, TPresence, TStorage>;
 
 export { type CreateBundle, type CreateRoomBundle, type CreateRoomBundleOptions, type InferRoomStorage, type PluvProviderProps, type PluvRoomProviderProps, type SubscriptionHookOptions, createBundle };

package/dist/index.d.ts

@@ -1,15 +1,15 @@
-import { PluvRoomAddon, PluvRoomDebug, WebSocketConnection, UserInfo, AbstractRoom, MockedRoomEvents, PluvClient } from '@pluv/client';
+import { PluvRouterEventConfig, PluvRoomAddon, PluvRouter, PluvRoomDebug, MergeEvents, WebSocketConnection, UserInfo, AbstractRoom, MockedRoomEvents, PluvClient } from '@pluv/client';
 export { ConnectionState, createClient } from '@pluv/client';
 import { CrdtType, AbstractCrdtDocFactory, AbstractCrdtDoc, InferCrdtJson } from '@pluv/crdt';
 export { CrdtType, InferCrdtJson } from '@pluv/crdt';
-import { IOLike, JsonObject, InputZodLike, Id, InferIOOutput, IOEventMessage, InferIOInput } from '@pluv/types';
+import { IOLike, JsonObject, Id, InferIOOutput, IOEventMessage, InferIOInput } from '@pluv/types';
 export { BaseUser, EventMessage, EventRecord, IOEventMessage } from '@pluv/types';
 import { FC, Dispatch, ReactNode } from 'react';
 
-type CreateRoomBundleOptions<TIO extends IOLike, TPresence extends JsonObject = {}, TStorage extends Record<string, CrdtType<any, any>> = {}> = {
-    addons?: readonly PluvRoomAddon<TIO, TPresence, TStorage>[];
+type CreateRoomBundleOptions<TIO extends IOLike, TMetadata extends JsonObject = {}, TPresence extends JsonObject = {}, TStorage extends Record<string, CrdtType<any, any>> = {}, TEvents extends PluvRouterEventConfig<TIO, TPresence, TStorage> = {}> = {
+    addons?: readonly PluvRoomAddon<TIO, TMetadata, TPresence, TStorage>[];
     initialStorage?: AbstractCrdtDocFactory<TStorage>;
-    presence?: InputZodLike<TPresence>;
+    router?: PluvRouter<TIO, TPresence, TStorage, TEvents>;
 };
 type BaseRoomProviderProps<TPresence extends JsonObject, TStorage extends Record<string, CrdtType<any, any>>> = {
     children?: ReactNode;
@@ -20,13 +20,17 @@ type BaseRoomProviderProps<TPresence extends JsonObject, TStorage extends Record
 } : {
     initialPresence: TPresence;
 });
-type MockedRoomProviderProps<TIO extends IOLike, TPresence extends JsonObject, TStorage extends Record<string, CrdtType<any, any>>> = BaseRoomProviderProps<TPresence, TStorage> & {
-    events?: MockedRoomEvents<TIO>;
+type MockedRoomProviderProps<TIO extends IOLike, TPresence extends JsonObject, TStorage extends Record<string, CrdtType<any, any>>, TEvents extends PluvRouterEventConfig<TIO, TPresence, TStorage> = {}> = BaseRoomProviderProps<TPresence, TStorage> & {
+    events?: MockedRoomEvents<MergeEvents<TEvents, TIO>>;
 };
-type PluvRoomProviderProps<TIO extends IOLike, TPresence extends JsonObject, TStorage extends Record<string, CrdtType<any, any>>> = BaseRoomProviderProps<TPresence, TStorage> & {
+type PluvRoomProviderProps<TIO extends IOLike, TMetadata extends JsonObject, TPresence extends JsonObject, TStorage extends Record<string, CrdtType<any, any>>> = BaseRoomProviderProps<TPresence, TStorage> & {
     debug?: boolean | PluvRoomDebug<TIO>;
     onAuthorizationFail?: (error: Error) => void;
-};
+} & (keyof TMetadata extends never ? {
+    metadata?: undefined;
+} : {
+    metadata: TMetadata;
+});
 interface SubscriptionHookOptions<T extends unknown> {
     isEqual?: (a: T, b: T) => boolean;
 }
@@ -39,16 +43,16 @@ type EventProxy<TIO extends IOLike> = {
         useEvent: (callback: (data: Id<IOEventMessage<TIO, event>>) => void) => void;
     };
 };
-interface CreateRoomBundle<TIO extends IOLike, TPresence extends JsonObject, TStorage extends Record<string, CrdtType<any, any>>> {
+interface CreateRoomBundle<TIO extends IOLike, TMetadata extends JsonObject, TPresence extends JsonObject, TStorage extends Record<string, CrdtType<any, any>>, TEvents extends PluvRouterEventConfig<TIO, TPresence, TStorage> = {}> {
     MockedRoomProvider: FC<MockedRoomProviderProps<TIO, TPresence, TStorage>>;
-    PluvRoomProvider: FC<PluvRoomProviderProps<TIO, TPresence, TStorage>>;
-    event: EventProxy<TIO>;
-    useBroadcast: () => BroadcastProxy<TIO>;
+    PluvRoomProvider: FC<PluvRoomProviderProps<TIO, TMetadata, TPresence, TStorage>>;
+    event: EventProxy<MergeEvents<TEvents, TIO>>;
+    useBroadcast: () => BroadcastProxy<MergeEvents<TEvents, TIO>>;
     useCanRedo: () => boolean;
     useCanUndo: () => boolean;
     useConnection: <T extends unknown = WebSocketConnection>(selector: (connection: WebSocketConnection) => T, options?: SubscriptionHookOptions<Id<T>>) => Id<T>;
     useDoc: () => AbstractCrdtDoc<TStorage>;
-    useEvent: <TType extends keyof InferIOOutput<TIO>>(type: TType, callback: (data: Id<IOEventMessage<TIO, TType>>) => void) => void;
+    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;
@@ -59,16 +63,16 @@ interface CreateRoomBundle<TIO extends IOLike, TPresence extends JsonObject, TSt
     useTransact: () => (fn: (storage: TStorage) => void, origin?: string) => void;
     useUndo: () => () => void;
 }
-type InferRoomStorage<TRoomBundle extends CreateRoomBundle<any, any, any>> = TRoomBundle extends CreateRoomBundle<any, any, infer IStorage> ? IStorage : never;
+type InferRoomStorage<TRoomBundle extends CreateRoomBundle<any, any, any, any, any>> = TRoomBundle extends CreateRoomBundle<any, any, any, infer IStorage> ? IStorage : never;
 
 interface PluvProviderProps {
     children?: ReactNode;
 }
-interface CreateBundle<TIO extends IOLike> {
-    createRoomBundle: <TPresence extends JsonObject = {}, TStorage extends Record<string, CrdtType<any, any>> = {}>(options: CreateRoomBundleOptions<TIO, TPresence, TStorage>) => CreateRoomBundle<TIO, TPresence, TStorage>;
+interface CreateBundle<TIO extends IOLike, TMetadata extends JsonObject, TPresence extends JsonObject = {}, TStorage extends Record<string, CrdtType<any, any>> = {}> {
+    createRoomBundle: <TEvents extends PluvRouterEventConfig<TIO, TPresence, TStorage> = {}>(options: CreateRoomBundleOptions<TIO, TMetadata, TPresence, TStorage, TEvents>) => CreateRoomBundle<TIO, TMetadata, TPresence, TStorage, TEvents>;
     PluvProvider: FC<PluvProviderProps>;
-    useClient: () => PluvClient<TIO>;
+    useClient: () => PluvClient<TIO, TPresence, TStorage, TMetadata>;
 }
-declare const createBundle: <TIO extends IOLike>(client: PluvClient<TIO>) => CreateBundle<TIO>;
+declare const createBundle: <TIO extends IOLike, TMetadata extends JsonObject = {}, TPresence extends JsonObject = {}, TStorage extends Record<string, CrdtType<any, any>> = {}>(client: PluvClient<TIO, TPresence, TStorage, TMetadata>) => CreateBundle<TIO, TMetadata, TPresence, TStorage>;
 
 export { type CreateBundle, type CreateRoomBundle, type CreateRoomBundleOptions, type InferRoomStorage, type PluvProviderProps, type PluvRoomProviderProps, type SubscriptionHookOptions, createBundle };

package/dist/index.js

@@ -122,15 +122,14 @@ var createRoomBundle = (client, options) => {
       return new import_client.MockedRoom(_room, {
         events,
         initialPresence,
-        initialStorage: typeof initialStorage === "function" ? _initialStorage.getFactory(initialStorage) : _initialStorage,
-        presence: options.presence
+        initialStorage: typeof initialStorage === "function" ? _initialStorage.getFactory(initialStorage) : _initialStorage
       });
     });
     return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(MockedRoomContext.Provider, { value: { room }, children: /* @__PURE__ */ (0, import_jsx_runtime.jsx)(PluvRoomContext.Provider, { value: room, children }) });
   });
   MockedRoomProvider.displayName = "MockedRoomProvider";
   const PluvRoomProvider = (0, import_react4.memo)((props) => {
-    const { children, debug, initialPresence, initialStorage, onAuthorizationFail, room: _room } = props;
+    const { children, debug, initialPresence, initialStorage, metadata, onAuthorizationFail, room: _room } = props;
     const rerender = useRerender();
     const { room: mockedRoom } = (0, import_react4.useContext)(MockedRoomContext);
     const [room] = (0, import_react4.useState)(() => {
@@ -139,8 +138,9 @@ var createRoomBundle = (client, options) => {
         debug,
         initialPresence,
         initialStorage: typeof initialStorage === "function" ? _initialStorage.getFactory(initialStorage) : _initialStorage,
-        presence: options.presence,
-        onAuthorizationFail
+        metadata,
+        onAuthorizationFail,
+        router: options.router
       });
     });
     (0, import_react4.useEffect)(() => {

package/dist/index.mjs

@@ -86,15 +86,14 @@ var createRoomBundle = (client, options) => {
       return new MockedRoom(_room, {
         events,
         initialPresence,
-        initialStorage: typeof initialStorage === "function" ? _initialStorage.getFactory(initialStorage) : _initialStorage,
-        presence: options.presence
+        initialStorage: typeof initialStorage === "function" ? _initialStorage.getFactory(initialStorage) : _initialStorage
       });
     });
     return /* @__PURE__ */ jsx(MockedRoomContext.Provider, { value: { room }, children: /* @__PURE__ */ jsx(PluvRoomContext.Provider, { value: room, children }) });
   });
   MockedRoomProvider.displayName = "MockedRoomProvider";
   const PluvRoomProvider = memo((props) => {
-    const { children, debug, initialPresence, initialStorage, onAuthorizationFail, room: _room } = props;
+    const { children, debug, initialPresence, initialStorage, metadata, onAuthorizationFail, room: _room } = props;
     const rerender = useRerender();
     const { room: mockedRoom } = useContext(MockedRoomContext);
     const [room] = useState3(() => {
@@ -103,8 +102,9 @@ var createRoomBundle = (client, options) => {
         debug,
         initialPresence,
         initialStorage: typeof initialStorage === "function" ? _initialStorage.getFactory(initialStorage) : _initialStorage,
-        presence: options.presence,
-        onAuthorizationFail
+        metadata,
+        onAuthorizationFail,
+        router: options.router
       });
     });
     useEffect2(() => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pluv/react",
-  "version": "0.25.4",
+  "version": "0.27.0",
   "description": "@pluv/client React.js bindings",
   "author": "leedavidcs",
   "license": "MIT",
@@ -18,22 +18,22 @@
   },
   "dependencies": {
     "fast-deep-equal": "^3.1.3",
-    "@pluv/client": "^0.25.4",
-    "@pluv/crdt": "^0.25.4",
-    "@pluv/types": "^0.25.4"
+    "@pluv/crdt": "^0.27.0",
+    "@pluv/types": "^0.27.0",
+    "@pluv/client": "^0.27.0"
   },
   "peerDependencies": {
     "@types/react": "^18.0.0",
     "react": "^18.0.0"
   },
   "devDependencies": {
-    "@types/react": "^18.3.4",
+    "@types/react": "^18.3.6",
     "eslint": "^8.57.0",
     "react": "^18.3.1",
-    "tsup": "^8.2.4",
-    "typescript": "^5.5.4",
-    "@pluv/tsconfig": "^0.25.4",
-    "eslint-config-pluv": "^0.25.4"
+    "tsup": "^8.3.0",
+    "typescript": "^5.6.2",
+    "@pluv/tsconfig": "^0.27.0",
+    "eslint-config-pluv": "^0.27.0"
   },
   "scripts": {
     "build": "tsup src/index.ts --format esm,cjs --dts --external react",

package/src/createBundle.tsx

@@ -1,4 +1,4 @@
-import type { PluvClient } from "@pluv/client";
+import type { PluvClient, PluvRouterEventConfig } from "@pluv/client";
 import type { CrdtType } from "@pluv/crdt";
 import type { IOLike, JsonObject } from "@pluv/types";
 import type { FC, ReactNode } from "react";
@@ -10,20 +10,32 @@ export interface PluvProviderProps {
     children?: ReactNode;
 }
 
-export interface CreateBundle<TIO extends IOLike> {
+export interface CreateBundle<
+    TIO extends IOLike,
+    TMetadata extends JsonObject,
+    TPresence extends JsonObject = {},
+    TStorage extends Record<string, CrdtType<any, any>> = {},
+> {
     // factories
-    createRoomBundle: <TPresence extends JsonObject = {}, TStorage extends Record<string, CrdtType<any, any>> = {}>(
-        options: CreateRoomBundleOptions<TIO, TPresence, TStorage>,
-    ) => CreateRoomBundle<TIO, TPresence, TStorage>;
+    createRoomBundle: <TEvents extends PluvRouterEventConfig<TIO, TPresence, TStorage> = {}>(
+        options: CreateRoomBundleOptions<TIO, TMetadata, TPresence, TStorage, TEvents>,
+    ) => CreateRoomBundle<TIO, TMetadata, TPresence, TStorage, TEvents>;
 
     // components
     PluvProvider: FC<PluvProviderProps>;
 
     // hooks
-    useClient: () => PluvClient<TIO>;
+    useClient: () => PluvClient<TIO, TPresence, TStorage, TMetadata>;
 }
 
-export const createBundle = <TIO extends IOLike>(client: PluvClient<TIO>): CreateBundle<TIO> => {
+export const createBundle = <
+    TIO extends IOLike,
+    TMetadata extends JsonObject = {},
+    TPresence extends JsonObject = {},
+    TStorage extends Record<string, CrdtType<any, any>> = {},
+>(
+    client: PluvClient<TIO, TPresence, TStorage, TMetadata>,
+): CreateBundle<TIO, TMetadata, TPresence, TStorage> => {
     /**
      * !HACK
      * @description We'll let the context error out if client is not provided,
@@ -31,7 +43,7 @@ export const createBundle = <TIO extends IOLike>(client: PluvClient<TIO>): Creat
      * @author leedavidcs
      * @date October 27, 2022
      */
-    const PluvContext = createContext<PluvClient<any>>(null as any);
+    const PluvContext = createContext<PluvClient<TIO, TPresence, TStorage, TMetadata>>(null as any);
 
     const PluvProvider = memo<PluvProviderProps>((props) => {
         const { children } = props;
@@ -41,14 +53,11 @@ export const createBundle = <TIO extends IOLike>(client: PluvClient<TIO>): Creat
 
     PluvProvider.displayName = "PluvProvider";
 
-    const useClient = (): PluvClient<TIO> => useContext(PluvContext);
+    const useClient = (): PluvClient<TIO, TPresence, TStorage, TMetadata> => useContext(PluvContext);
 
-    const createRoomBundle = <
-        TPresence extends JsonObject = {},
-        TStorage extends Record<string, CrdtType<any, any>> = {},
-    >(
-        options: CreateRoomBundleOptions<TIO, TPresence, TStorage>,
-    ): CreateRoomBundle<TIO, TPresence, TStorage> => _createRoomBundle(client, options);
+    const createRoomBundle = <TEvents extends PluvRouterEventConfig<TIO, TPresence, TStorage> = {}>(
+        options: CreateRoomBundleOptions<TIO, TMetadata, TPresence, TStorage, TEvents>,
+    ): CreateRoomBundle<TIO, TMetadata, TPresence, TStorage, TEvents> => _createRoomBundle(client, options);
 
     return {
         createRoomBundle,

package/src/createRoomBundle.tsx

@@ -1,17 +1,21 @@
 import type {
     AbstractRoom,
+    CreateRoomOptions,
+    MergeEvents,
     MockedRoomEvents,
     PluvClient,
     PluvRoom,
     PluvRoomAddon,
     PluvRoomDebug,
+    PluvRouter,
+    PluvRouterEventConfig,
     UserInfo,
     WebSocketConnection,
 } from "@pluv/client";
 import { MockedRoom } from "@pluv/client";
 import type { AbstractCrdtDoc, AbstractCrdtDocFactory, CrdtType, InferCrdtJson } from "@pluv/crdt";
 import { noop } from "@pluv/crdt";
-import type { IOEventMessage, IOLike, Id, InferIOInput, InferIOOutput, InputZodLike, JsonObject } from "@pluv/types";
+import type { IOEventMessage, IOLike, Id, InferIOInput, InferIOOutput, JsonObject } from "@pluv/types";
 import fastDeepEqual from "fast-deep-equal";
 import type { Dispatch, FC, ReactNode } from "react";
 import { createContext, memo, useCallback, useContext, useEffect, useMemo, useState } from "react";
@@ -19,12 +23,14 @@ import { identity, shallowArrayEqual, useRerender, useSyncExternalStoreWithSelec
 
 export type CreateRoomBundleOptions<
     TIO extends IOLike,
+    TMetadata extends JsonObject = {},
     TPresence extends JsonObject = {},
     TStorage extends Record<string, CrdtType<any, any>> = {},
+    TEvents extends PluvRouterEventConfig<TIO, TPresence, TStorage> = {},
 > = {
-    addons?: readonly PluvRoomAddon<TIO, TPresence, TStorage>[];
+    addons?: readonly PluvRoomAddon<TIO, TMetadata, TPresence, TStorage>[];
     initialStorage?: AbstractCrdtDocFactory<TStorage>;
-    presence?: InputZodLike<TPresence>;
+    router?: PluvRouter<TIO, TPresence, TStorage, TEvents>;
 };
 
 type BaseRoomProviderProps<TPresence extends JsonObject, TStorage extends Record<string, CrdtType<any, any>>> = {
@@ -37,18 +43,20 @@ export type MockedRoomProviderProps<
     TIO extends IOLike,
     TPresence extends JsonObject,
     TStorage extends Record<string, CrdtType<any, any>>,
+    TEvents extends PluvRouterEventConfig<TIO, TPresence, TStorage> = {},
 > = BaseRoomProviderProps<TPresence, TStorage> & {
-    events?: MockedRoomEvents<TIO>;
+    events?: MockedRoomEvents<MergeEvents<TEvents, TIO>>;
 };
 
 export type PluvRoomProviderProps<
     TIO extends IOLike,
+    TMetadata extends JsonObject,
     TPresence extends JsonObject,
     TStorage extends Record<string, CrdtType<any, any>>,
 > = BaseRoomProviderProps<TPresence, TStorage> & {
     debug?: boolean | PluvRoomDebug<TIO>;
     onAuthorizationFail?: (error: Error) => void;
-};
+} & (keyof TMetadata extends never ? { metadata?: undefined } : { metadata: TMetadata });
 
 export interface SubscriptionHookOptions<T extends unknown> {
     isEqual?: (a: T, b: T) => boolean;
@@ -73,18 +81,20 @@ export type EventProxy<TIO extends IOLike> = {
 
 export interface CreateRoomBundle<
     TIO extends IOLike,
+    TMetadata extends JsonObject,
     TPresence extends JsonObject,
     TStorage extends Record<string, CrdtType<any, any>>,
+    TEvents extends PluvRouterEventConfig<TIO, TPresence, TStorage> = {},
 > {
     // components
     MockedRoomProvider: FC<MockedRoomProviderProps<TIO, TPresence, TStorage>>;
-    PluvRoomProvider: FC<PluvRoomProviderProps<TIO, TPresence, TStorage>>;
+    PluvRoomProvider: FC<PluvRoomProviderProps<TIO, TMetadata, TPresence, TStorage>>;
 
     // proxies
-    event: EventProxy<TIO>;
+    event: EventProxy<MergeEvents<TEvents, TIO>>;
 
     // hooks
-    useBroadcast: () => BroadcastProxy<TIO>;
+    useBroadcast: () => BroadcastProxy<MergeEvents<TEvents, TIO>>;
     useCanRedo: () => boolean;
     useCanUndo: () => boolean;
     useConnection: <T extends unknown = WebSocketConnection>(
@@ -92,9 +102,9 @@ export interface CreateRoomBundle<
         options?: SubscriptionHookOptions<Id<T>>,
     ) => Id<T>;
     useDoc: () => AbstractCrdtDoc<TStorage>;
-    useEvent: <TType extends keyof InferIOOutput<TIO>>(
+    useEvent: <TType extends keyof InferIOOutput<MergeEvents<TEvents, TIO>>>(
         type: TType,
-        callback: (data: Id<IOEventMessage<TIO, TType>>) => void,
+        callback: (data: Id<IOEventMessage<MergeEvents<TEvents, TIO>, TType>>) => void,
     ) => void;
     useMyPresence: <T extends unknown = TPresence>(
         selector?: (myPresence: TPresence) => T,
@@ -124,17 +134,19 @@ export interface CreateRoomBundle<
     useUndo: () => () => void;
 }
 
-export type InferRoomStorage<TRoomBundle extends CreateRoomBundle<any, any, any>> =
-    TRoomBundle extends CreateRoomBundle<any, any, infer IStorage> ? IStorage : never;
+export type InferRoomStorage<TRoomBundle extends CreateRoomBundle<any, any, any, any, any>> =
+    TRoomBundle extends CreateRoomBundle<any, any, any, infer IStorage> ? IStorage : never;
 
 export const createRoomBundle = <
     TIO extends IOLike,
+    TMetadata extends JsonObject = {},
     TPresence extends JsonObject = {},
     TStorage extends Record<string, CrdtType<any, any>> = {},
+    TEvents extends PluvRouterEventConfig<TIO, TPresence, TStorage> = {},
 >(
-    client: PluvClient<TIO>,
-    options: CreateRoomBundleOptions<TIO, TPresence, TStorage>,
-): CreateRoomBundle<TIO, TPresence, TStorage> => {
+    client: PluvClient<TIO, TPresence, TStorage, TMetadata>,
+    options: CreateRoomBundleOptions<TIO, TMetadata, TPresence, TStorage, TEvents>,
+): CreateRoomBundle<TIO, TMetadata, TPresence, TStorage, TEvents> => {
     const _initialStorage = (options.initialStorage ?? noop.doc()) as AbstractCrdtDocFactory<TStorage>;
 
     /**
@@ -153,13 +165,12 @@ export const createRoomBundle = <
     const MockedRoomProvider = memo<MockedRoomProviderProps<TIO, TPresence, TStorage>>((props) => {
         const { children, events, initialPresence, initialStorage, room: _room } = props;
 
-        const [room] = useState<MockedRoom<TIO, TPresence, TStorage>>(() => {
-            return new MockedRoom<TIO, TPresence, TStorage>(_room, {
+        const [room] = useState<MockedRoom<TIO, TPresence, TStorage, TEvents>>(() => {
+            return new MockedRoom<TIO, TPresence, TStorage, TEvents>(_room, {
                 events,
                 initialPresence,
                 initialStorage:
                     typeof initialStorage === "function" ? _initialStorage.getFactory(initialStorage) : _initialStorage,
-                presence: options.presence,
             });
         });
 
@@ -172,22 +183,23 @@ export const createRoomBundle = <
 
     MockedRoomProvider.displayName = "MockedRoomProvider";
 
-    const PluvRoomProvider = memo<PluvRoomProviderProps<TIO, TPresence, TStorage>>((props) => {
-        const { children, debug, initialPresence, initialStorage, onAuthorizationFail, room: _room } = props;
+    const PluvRoomProvider = memo<PluvRoomProviderProps<TIO, TMetadata, TPresence, TStorage>>((props) => {
+        const { children, debug, initialPresence, initialStorage, metadata, onAuthorizationFail, room: _room } = props;
 
         const rerender = useRerender();
         const { room: mockedRoom } = useContext(MockedRoomContext);
 
-        const [room] = useState<PluvRoom<TIO, TPresence, TStorage>>(() => {
-            return client.createRoom<TPresence, TStorage>(_room, {
+        const [room] = useState<PluvRoom<TIO, TMetadata, TPresence, TStorage, TEvents>>(() => {
+            return client.createRoom(_room, {
                 addons: options.addons,
                 debug,
                 initialPresence,
                 initialStorage:
                     typeof initialStorage === "function" ? _initialStorage.getFactory(initialStorage) : _initialStorage,
-                presence: options.presence,
+                metadata,
                 onAuthorizationFail,
-            });
+                router: options.router,
+            } as CreateRoomOptions<TIO, TPresence, TStorage, TMetadata, TEvents>);
         });
 
         useEffect(() => {
@@ -215,24 +227,31 @@ export const createRoomBundle = <
 
     const useRoom = () => useContext(PluvRoomContext);
 
-    const useBroadcast = (): BroadcastProxy<TIO> => {
+    const useBroadcast = (): BroadcastProxy<MergeEvents<TEvents, TIO>> => {
         const room = useRoom();
 
         const broadcast = useCallback(
-            <TEvent extends keyof InferIOInput<TIO>>(event: TEvent, data: Id<InferIOInput<TIO>[TEvent]>) => {
+            <TEvent extends keyof InferIOInput<MergeEvents<TEvents, TIO>>>(
+                event: TEvent,
+                data: Id<InferIOInput<MergeEvents<TEvents, TIO>>[TEvent]>,
+            ) => {
                 room.broadcast(event, data);
             },
             [room],
         );
 
-        return useMemo((): BroadcastProxy<TIO> => {
+        return useMemo((): BroadcastProxy<MergeEvents<TEvents, TIO>> => {
             return new Proxy(broadcast, {
                 get(fn, prop) {
-                    return (data: Id<InferIOInput<TIO>[keyof InferIOInput<TIO>]>): void => {
-                        return fn(prop as keyof InferIOInput<TIO>, data);
+                    return (
+                        data: Id<
+                            InferIOInput<MergeEvents<TEvents, TIO>>[keyof InferIOInput<MergeEvents<TEvents, TIO>>]
+                        >,
+                    ): void => {
+                        return fn(prop as keyof InferIOInput<MergeEvents<TEvents, TIO>>, data);
                     };
                 },
-            }) as BroadcastProxy<TIO>;
+            }) as BroadcastProxy<MergeEvents<TEvents, TIO>>;
         }, [broadcast]);
     };
 
@@ -292,9 +311,9 @@ export const createRoomBundle = <
         return room.getDoc();
     };
 
-    const useEvent = <TType extends keyof InferIOOutput<TIO>>(
+    const useEvent = <TType extends keyof InferIOOutput<MergeEvents<TEvents, TIO>>>(
         type: TType,
-        callback: (data: Id<IOEventMessage<TIO, TType>>) => void,
+        callback: (data: Id<IOEventMessage<MergeEvents<TEvents, TIO>, TType>>) => void,
     ): void => {
         const room = useRoom();
 
@@ -312,15 +331,19 @@ export const createRoomBundle = <
         {
             get(_, prop) {
                 const useProxyEvent = (
-                    callback: (data: Id<IOEventMessage<TIO, keyof InferIOOutput<TIO>>>) => void,
+                    callback: (
+                        data: Id<
+                            IOEventMessage<MergeEvents<TEvents, TIO>, keyof InferIOOutput<MergeEvents<TEvents, TIO>>>
+                        >,
+                    ) => void,
                 ): void => {
-                    return useEvent(prop as keyof InferIOOutput<TIO>, callback);
+                    return useEvent(prop as keyof InferIOOutput<MergeEvents<TEvents, TIO>>, callback);
                 };
 
                 return { useEvent: useProxyEvent };
             },
         },
-    ) as EventProxy<TIO>;
+    ) as EventProxy<MergeEvents<TEvents, TIO>>;
 
     const useMyPresence = <T extends unknown = TPresence>(
         selector = identity as (myPresence: TPresence) => T,

package/src/internal/hooks/useSyncExternalStoreWithSelector.ts

@@ -26,7 +26,7 @@ export const useSyncExternalStoreWithSelector = <TSnapshot, TSelection>(
                * @description Memoize only the last snapshot so that we can only rerender on changes
                * @date June 22, 2024
                */
-              cacheRef.current = isUnchanged ? cached ?? snapshot : snapshot;
+              cacheRef.current = isUnchanged ? (cached ?? snapshot) : snapshot;
 
               return cacheRef.current;
           }
@@ -45,7 +45,7 @@ export const useSyncExternalStoreWithSelector = <TSnapshot, TSelection>(
          * @description Memoize only the last snapshot so that we can only rerender on changes
          * @date June 22, 2024
          */
-        cacheRef.current = isUnchanged ? cached ?? snapshot : snapshot;
+        cacheRef.current = isUnchanged ? (cached ?? snapshot) : snapshot;
 
         return cacheRef.current;
     };

package/src/internal/index.ts

@@ -1,2 +1,2 @@
-export { useRerender, useSyncExternalStore, useSyncExternalStoreWithSelector } from "./hooks";
+export { useRerender, useSyncExternalStoreWithSelector } from "./hooks";
 export { identity, shallowArrayEqual } from "./utils";