@microsoft/live-share-react 1.0.0-preview.21 → 1.0.0-preview.23

package/src/live-hooks/useLiveState.ts

@@ -7,6 +7,13 @@ import { LiveState, UserMeetingRole } from "@microsoft/live-share";
 import React from "react";
 import { SetLiveStateAction } from "../types";
 import { useDynamicDDS } from "../shared-hooks";
+import { useFluidObjectsContext } from "../providers";
+import {
+    ActionContainerNotJoinedError,
+    ActionLiveDataObjectInitializedError,
+    ActionLiveDataObjectUndefinedError,
+    isPrevStateCallback,
+} from "../internal";
 
 /**
  * React hook for using a Live Share `LiveState`.
@@ -20,11 +27,11 @@ import { useDynamicDDS } from "../shared-hooks";
  * @returns ordered values: first value is the synchronized state value and the second is a setter to change the state value.
  * The setter returns a void promise, which will throw if the user does not have the required roles to set.
  */
-export function useLiveState<TState = any>(
+export function useLiveState<TState>(
     uniqueKey: string,
     initialState: TState,
     allowedRoles?: UserMeetingRole[]
-): [TState, SetLiveStateAction<TState>] {
+): [TState, SetLiveStateAction<TState>, LiveState<TState> | undefined] {
     const [currentState, setCurrentState] =
         React.useState<TState>(initialState);
     /**
@@ -35,32 +42,39 @@ export function useLiveState<TState = any>(
         LiveState<TState>
     );
 
+    const { container } = useFluidObjectsContext();
+
     /**
      * Change state callback that is user facing
      * @param state TState to set
      * @returns void promise, which will throw if the user does not have the required roles
      */
     const setState = React.useCallback(
-        async (state: TState) => {
-            if (!liveState) {
-                console.error(
-                    new Error(
-                        "Cannot call changeState when liveState is undefined"
-                    )
+        async (state: TState | ((prevState: TState) => TState)) => {
+            if (!container) {
+                throw new ActionContainerNotJoinedError(
+                    "liveState",
+                    "setState"
+                );
+            }
+            if (liveState === undefined) {
+                throw new ActionLiveDataObjectUndefinedError(
+                    "liveState",
+                    "setState"
                 );
-                return;
             }
             if (!liveState.isInitialized) {
-                console.error(
-                    new Error(
-                        "Cannot call changeState while liveState is not started"
-                    )
+                throw new ActionLiveDataObjectInitializedError(
+                    "liveState",
+                    "setState"
                 );
-                return;
             }
-            return await liveState.set(state);
+            const valueToSet = isPrevStateCallback<TState>(state)
+                ? state(liveState.state)
+                : state;
+            return await liveState.set(valueToSet);
         },
-        [liveState]
+        [container, liveState]
     );
 
     /**
@@ -85,5 +99,5 @@ export function useLiveState<TState = any>(
         };
     }, [liveState]);
 
-    return [currentState, setState];
+    return [currentState, setState, liveState];
 }

package/src/live-hooks/useLiveTimer.ts

@@ -22,6 +22,12 @@ import {
     OnTimerTickAction,
 } from "../types";
 import { useDynamicDDS } from "../shared-hooks";
+import { useFluidObjectsContext } from "../providers";
+import {
+    ActionContainerNotJoinedError,
+    ActionLiveDataObjectInitializedError,
+    ActionLiveDataObjectUndefinedError,
+} from "../internal";
 
 export function useLiveTimer(
     uniqueKey: string,
@@ -46,6 +52,8 @@ export function useLiveTimer(
      */
     const { dds: liveTimer } = useDynamicDDS<LiveTimer>(uniqueKey, LiveTimer);
 
+    const { container } = useFluidObjectsContext();
+
     /**
      * Callback to send event through `LiveTimer`
      * @param duration the duration for the timer in milliseconds
@@ -53,23 +61,24 @@ export function useLiveTimer(
      */
     const start: OnStartTimerAction = React.useCallback(
         async (duration: number) => {
+            if (!container) {
+                throw new ActionContainerNotJoinedError("liveTimer", "start");
+            }
             if (liveTimer === undefined) {
-                console.error(
-                    new Error("Cannot call start when liveTimer is undefined")
+                throw new ActionLiveDataObjectUndefinedError(
+                    "liveTimer",
+                    "start"
                 );
-                return;
             }
             if (!liveTimer.isInitialized) {
-                console.error(
-                    new Error(
-                        "Cannot call start while liveTimer is not started"
-                    )
+                throw new ActionLiveDataObjectInitializedError(
+                    "liveTimer",
+                    "start"
                 );
-                return;
             }
             return await liveTimer.start(duration);
         },
-        [liveTimer]
+        [container, liveTimer]
     );
 
     /**
@@ -77,40 +86,37 @@ export function useLiveTimer(
      * @returns void promise that will throw when user does not have required roles
      */
     const play: OnPlayTimerAction = React.useCallback(async () => {
+        if (!container) {
+            throw new ActionContainerNotJoinedError("liveTimer", "play");
+        }
         if (liveTimer === undefined) {
-            console.error(
-                new Error("Cannot call play when liveTimer is undefined")
-            );
-            return;
+            throw new ActionLiveDataObjectUndefinedError("liveTimer", "play");
         }
         if (!liveTimer.isInitialized) {
-            console.error(
-                new Error("Cannot call play while liveTimer is not started")
-            );
-            return;
+            throw new ActionLiveDataObjectInitializedError("liveTimer", "play");
         }
         return await liveTimer.play();
-    }, [liveTimer]);
+    }, [container, liveTimer]);
 
     /**
      * Callback to send event through `LiveTimer`
      * @returns void promise that will throw when user does not have required roles
      */
     const pause: OnPauseTimerAction = React.useCallback(async () => {
+        if (!container) {
+            throw new ActionContainerNotJoinedError("liveTimer", "pause");
+        }
         if (liveTimer === undefined) {
-            console.error(
-                new Error("Cannot call pause when liveTimer is undefined")
-            );
-            return;
+            throw new ActionLiveDataObjectUndefinedError("liveTimer", "pause");
         }
         if (!liveTimer.isInitialized) {
-            console.error(
-                new Error("Cannot call pause while liveTimer is not started")
+            throw new ActionLiveDataObjectInitializedError(
+                "liveTimer",
+                "pause"
             );
-            return;
         }
         return await liveTimer.pause();
-    }, [liveTimer]);
+    }, [container, liveTimer]);
 
     /**
      * Setup change listeners and start `LiveTimer` if needed

package/src/live-hooks/useMediaSynchronizer.ts

@@ -16,6 +16,12 @@ import {
 import { isExtendedMediaMetadata, isMediaElement, isRefObject } from "../utils";
 import { useDynamicDDS } from "../shared-hooks";
 import { IUseMediaSynchronizerResults } from "../types";
+import { useFluidObjectsContext } from "../providers";
+import {
+    ActionContainerNotJoinedError,
+    ActionLiveDataObjectInitializedError,
+    ActionLiveDataObjectUndefinedError,
+} from "../internal";
 
 /**
  * React hook for using a Live Share media `MediaPlayerSynchronizer`.
@@ -57,31 +63,66 @@ export function useMediaSynchronizer(
         LiveMediaSession
     );
 
+    const { container } = useFluidObjectsContext();
+
     /**
      * Play callback
      */
     const play = React.useCallback(async () => {
-        if (!mediaSynchronizer) return;
+        if (!container) {
+            throw new ActionContainerNotJoinedError(
+                "mediaSynchronizer",
+                "play"
+            );
+        }
+        if (mediaSynchronizer === undefined) {
+            throw new ActionLiveDataObjectUndefinedError(
+                "mediaSynchronizer",
+                "play"
+            );
+        }
         return await mediaSynchronizer.play();
-    }, [mediaSynchronizer]);
+    }, [container, mediaSynchronizer]);
 
     /**
      * Pause callback
      */
     const pause = React.useCallback(async () => {
-        if (!mediaSynchronizer) return;
+        if (!container) {
+            throw new ActionContainerNotJoinedError(
+                "mediaSynchronizer",
+                "pause"
+            );
+        }
+        if (mediaSynchronizer === undefined) {
+            throw new ActionLiveDataObjectUndefinedError(
+                "mediaSynchronizer",
+                "pause"
+            );
+        }
         return await mediaSynchronizer.pause();
-    }, [mediaSynchronizer]);
+    }, [container, mediaSynchronizer]);
 
     /**
      * User facing: seek callback
      */
     const seekTo = React.useCallback(
         async (time: number) => {
-            if (!mediaSynchronizer) return;
+            if (!container) {
+                throw new ActionContainerNotJoinedError(
+                    "mediaSynchronizer",
+                    "seekTo"
+                );
+            }
+            if (mediaSynchronizer === undefined) {
+                throw new ActionLiveDataObjectUndefinedError(
+                    "mediaSynchronizer",
+                    "seekTo"
+                );
+            }
             return await mediaSynchronizer.seekTo(time);
         },
-        [mediaSynchronizer]
+        [container, mediaSynchronizer]
     );
 
     /**
@@ -89,7 +130,18 @@ export function useMediaSynchronizer(
      */
     const setTrack = React.useCallback(
         async (track: Partial<ExtendedMediaMetadata> | string | null) => {
-            if (!mediaSynchronizer) return;
+            if (!container) {
+                throw new ActionContainerNotJoinedError(
+                    "mediaSynchronizer",
+                    "setTrack"
+                );
+            }
+            if (mediaSynchronizer === undefined) {
+                throw new ActionLiveDataObjectUndefinedError(
+                    "mediaSynchronizer",
+                    "setTrack"
+                );
+            }
             if (isExtendedMediaMetadata(track)) {
                 return await mediaSynchronizer.setTrack(track);
             } else if (typeof track === "string") {
@@ -98,7 +150,7 @@ export function useMediaSynchronizer(
                 } as ExtendedMediaMetadata);
             }
         },
-        [mediaSynchronizer]
+        [container, mediaSynchronizer]
     );
 
     /**

package/src/providers/AzureProvider.tsx

@@ -13,7 +13,7 @@ import { IAzureContainerResults } from "../types";
 import {
     ISharedStateRegistryResponse,
     useSharedStateRegistry,
-} from "../internal-hooks";
+} from "../internal";
 import {
     AzureTurboClient,
     IFluidTurboClient,

package/src/providers/LiveShareProvider.tsx

@@ -5,7 +5,7 @@
 
 import { IFluidContainer, LoadableObjectClassRecord } from "fluid-framework";
 import React from "react";
-import { useSharedStateRegistry } from "../internal-hooks";
+import { useSharedStateRegistry } from "../internal";
 import {
     ILiveShareClientOptions,
     ILiveShareHost,

package/src/shared-hooks/useSharedMap.ts

@@ -8,6 +8,11 @@ import { isEntries, isJSON, isMap } from "../utils";
 import { IUseSharedMapResults, SharedMapInitialData } from "../types";
 import { useDynamicDDS } from "./useDynamicDDS";
 import { SharedMap } from "fluid-framework";
+import { useFluidObjectsContext } from "../providers";
+import {
+    ActionContainerNotJoinedError,
+    ActionLiveDataObjectUndefinedError,
+} from "../internal";
 
 /**
  * React hook for using a Fluid `SharedMap`.
@@ -56,20 +61,28 @@ export function useSharedMap<TData extends object = object>(
         onFirstInitialize
     );
 
+    const { container } = useFluidObjectsContext();
+
     /**
      * User facing: set a value to the Fluid `SharedMap`.
      */
     const setEntry = React.useCallback(
         (key: string, value: TData) => {
-            if (!sharedMap) {
-                console.error(
-                    new Error("Cannot call set when sharedMap is undefined")
+            if (!container) {
+                throw new ActionContainerNotJoinedError(
+                    "sharedMap",
+                    "setEntry"
+                );
+            }
+            if (sharedMap === undefined) {
+                throw new ActionLiveDataObjectUndefinedError(
+                    "sharedMap",
+                    "setEntry"
                 );
-                return;
             }
             sharedMap.set(key, value);
         },
-        [sharedMap]
+        [container, sharedMap]
     );
 
     /**
@@ -77,15 +90,21 @@ export function useSharedMap<TData extends object = object>(
      */
     const deleteEntry = React.useCallback(
         (key: string) => {
-            if (!sharedMap) {
-                console.error(
-                    new Error("Cannot call remove when sharedMap is undefined")
+            if (!container) {
+                throw new ActionContainerNotJoinedError(
+                    "sharedMap",
+                    "deleteEntry"
+                );
+            }
+            if (sharedMap === undefined) {
+                throw new ActionLiveDataObjectUndefinedError(
+                    "sharedMap",
+                    "deleteEntry"
                 );
-                return;
             }
             sharedMap.delete(key);
         },
-        [sharedMap]
+        [container, sharedMap]
     );
 
     // Setup change listeners, initial values, etc.

package/src/shared-hooks/useSharedState.ts

@@ -7,6 +7,7 @@ import React from "react";
 import { useFluidObjectsContext } from "../providers";
 import { DisposeSharedStateAction, SetSharedStateAction } from "../types";
 import { v4 as uuid } from "uuid";
+import { isPrevStateCallback } from "../internal";
 
 /**
  * Inspired by React's `useState` hook, `useSharedState` makes it easy to synchronize state in your app.
@@ -48,9 +49,14 @@ export function useSharedState<S>(
      * User facing: callback to change the shared state.
      */
     const setSharedState: SetSharedStateAction<S> = React.useCallback(
-        (updatedState: S) => {
-            setLocalState(updatedState);
-            updateSharedState(uniqueKey, updatedState);
+        (state: S | ((prevState: S) => S)) => {
+            setLocalState((prevState) => {
+                const valueToSet = isPrevStateCallback<S>(state)
+                    ? state(prevState)
+                    : state;
+                updateSharedState(uniqueKey, valueToSet);
+                return valueToSet;
+            });
         },
         [uniqueKey, setLocalState, updateSharedState]
     );

package/src/types/ActionTypes.ts

@@ -10,7 +10,15 @@ import { ITimerConfig, ILiveEvent, PresenceState } from "@microsoft/live-share";
 
 // React actions
 
-export type SetSharedStateAction<T> = (state: T) => void;
+/**
+ * Callback to set shared state
+ */
+export type SetSharedStateAction<TState> = (
+    state: TState | ((prevState: TState) => TState)
+) => void;
+/**
+ * Callback to set local state
+ */
 export type SetLocalStateAction = React.Dispatch<React.SetStateAction<any>>;
 
 // Fluid actions
@@ -79,7 +87,7 @@ export type DisposeSharedStateAction = () => void;
  * (state: TState) => Promise<void>
  */
 export type SetLiveStateAction<TState = undefined> = (
-    state: TState
+    state: TState | ((prevState: TState) => TState)
 ) => Promise<void>;
 
 /**

package/src/internal-hooks/index.ts

@@ -1 +0,0 @@
-export * from "./useSharedStateRegistry";