feat: remove -Instance suffix and rename to useXXXReturn

Author: 1egoman

packages/react/src/hooks/useAgent.ts

@@ -7,7 +7,7 @@ import { ParticipantAgentAttributes, TrackReference } from '@livekit/components-
 
 import { useParticipantTracks } from './useParticipantTracks';
 import { useRemoteParticipants } from './useRemoteParticipants';
-import { ConversationInstance } from './useConversationWith';
+import { UseConversationReturn } from './useConversationWith';
 
 // FIXME: make this 10 seconds once room dispatch booting info is discoverable
 const DEFAULT_AGENT_CONNECT_TIMEOUT_MILLISECONDS = 20_000;
@@ -46,9 +46,7 @@ export type AgentCallbacks = {
   [AgentEvent.StateChanged]: (newAgentState: AgentState) => void;
 };
 
-type AgentInstanceCommon = {
-  [Symbol.toStringTag]: "AgentInstance";
-
+type AgentStateCommon = {
   // FIXME: maybe add some sort of schema to this?
   attributes: Record<string, string>;
 
@@ -60,7 +58,7 @@ type AgentInstanceCommon = {
   };
 };
 
-type AgentStateAvailable = AgentInstanceCommon & {
+type AgentStateAvailable = AgentStateCommon & {
   state: "thinking" | "speaking";
   failureReasons: null;
 
@@ -74,7 +72,7 @@ type AgentStateAvailable = AgentInstanceCommon & {
   microphoneTrack: TrackReference | null;
 };
 
-type AgentStateAvailableListening = AgentInstanceCommon & {
+type AgentStateAvailableListening = AgentStateCommon & {
   state: "listening";
   failureReasons: null;
 
@@ -88,7 +86,7 @@ type AgentStateAvailableListening = AgentInstanceCommon & {
   microphoneTrack: TrackReference | null;
 };
 
-type AgentStateUnAvailable = AgentInstanceCommon & {
+type AgentStateUnAvailable = AgentStateCommon & {
   state: "initializing" | "idle";
   failureReasons: null;
 
@@ -102,7 +100,7 @@ type AgentStateUnAvailable = AgentInstanceCommon & {
   microphoneTrack: TrackReference | null;
 };
 
-type AgentStateConnecting = AgentInstanceCommon & {
+type AgentStateConnecting = AgentStateCommon & {
   state: "disconnected" | "connecting";
   failureReasons: null;
 
@@ -116,7 +114,7 @@ type AgentStateConnecting = AgentInstanceCommon & {
   microphoneTrack: null;
 };
 
-type AgentStateFailed = AgentInstanceCommon & {
+type AgentStateFailed = AgentStateCommon & {
   state: "failed";
   failureReasons: Array<string>;
 
@@ -142,7 +140,7 @@ type AgentActions = {
 };
 
 type AgentStateCases = AgentStateConnecting | AgentStateAvailable | AgentStateAvailableListening | AgentStateUnAvailable | AgentStateFailed;
-export type AgentInstance = AgentStateCases & AgentActions;
+export type UseAgentReturn = AgentStateCases & AgentActions;
 
 const generateDerivedStateValues = <State extends AgentState>(state: State) => ({
   isAvailable: (
@@ -235,12 +233,12 @@ const useAgentTimeoutIdStore = create<{
   };
 });
 
-type ConversationStub = Pick<ConversationInstance, 'connectionState' | 'subtle'>;
+type ConversationStub = Pick<UseConversationReturn, 'connectionState' | 'subtle'>;
 
 /**
   * useAgent encapculates all agent state, normalizing some quirks around how LiveKit Agents work.
   */
-export function useAgent(conversation: ConversationStub, _name?: string): AgentInstance {
+export function useAgent(conversation: ConversationStub, _name?: string): UseAgentReturn {
   const { room } = conversation.subtle;
 
   const emitter = useMemo(() => new EventEmitter() as TypedEventEmitter<AgentCallbacks>, []);
@@ -268,7 +266,7 @@ export function useAgent(conversation: ConversationStub, _name?: string): AgentI
       return;
     }
 
-    const handleAttributesChanged = (attributes: AgentInstance["attributes"]) => {
+    const handleAttributesChanged = (attributes: UseAgentReturn["attributes"]) => {
       setAgentParticipantAttributes(attributes);
       emitter.emit(AgentEvent.AttributesChanged, attributes);
     };
@@ -397,9 +395,7 @@ export function useAgent(conversation: ConversationStub, _name?: string): AgentI
   }, [isConversationDisconnected, conversation.subtle.agentConnectTimeoutMilliseconds]);
 
   const agentState: AgentStateCases = useMemo(() => {
-    const common: AgentInstanceCommon = {
-      [Symbol.toStringTag]: "AgentInstance",
-
+    const common: AgentStateCommon = {
       attributes: agentParticipantAttributes,
 
       subtle: {
@@ -508,7 +504,7 @@ export function useAgent(conversation: ConversationStub, _name?: string): AgentI
       };
       const abortHandler = () => {
         cleanup();
-        reject(new Error('AgentInstance.waitUntilAvailable - signal aborted'));
+        reject(new Error('useAgent.waitUntilAvailable - signal aborted'));
       };
 
       const cleanup = () => {
@@ -532,7 +528,7 @@ export function useAgent(conversation: ConversationStub, _name?: string): AgentI
       };
       const abortHandler = () => {
         cleanup();
-        reject(new Error('AgentInstance.waitUntilCamera - signal aborted'));
+        reject(new Error('useAgent.waitUntilCamera - signal aborted'));
       };
 
       const cleanup = () => {
@@ -556,7 +552,7 @@ export function useAgent(conversation: ConversationStub, _name?: string): AgentI
       };
       const abortHandler = () => {
         cleanup();
-        reject(new Error('AgentInstance.waitUntilMicrophone - signal aborted'));
+        reject(new Error('useAgent.waitUntilMicrophone - signal aborted'));
       };
 
       const cleanup = () => {

packages/react/src/hooks/useConversationMessages.ts

@@ -13,11 +13,9 @@ import {
 import { useAgent } from './useAgent';
 import { useTranscriptions } from './useTranscriptions';
 import { useChat } from './useChat';
-import { ConversationInstance } from './useConversationWith';
-
-export type MessagesInstance = {
-  [Symbol.toStringTag]: "MessagesInstance",
+import { UseConversationReturn } from './useConversationWith';
 
+export type UseConversationMessagesReturn = {
   messages: Array<ReceivedMessage>;
 
   /** Is a send operation currently in progress? */
@@ -40,7 +38,7 @@ export type MessagesCallbacks = {
   [MessagesEvent.MessageReceived]: (message: ReceivedMessage) => void;
 };
 
-export function useConversationMessages(conversation: ConversationInstance): MessagesInstance {
+export function useConversationMessages(conversation: UseConversationReturn): UseConversationMessagesReturn {
   const { room } = conversation.subtle;
 
   const agent = useAgent(conversation);
@@ -103,8 +101,6 @@ export function useConversationMessages(conversation: ConversationInstance): Mes
   }, [transcriptionMessages, chat.chatMessages]);
 
   return useMemo(() => ({
-    [Symbol.toStringTag]: "MessagesInstance",
-
     messages: receivedMessages,
     send: chat.send,
     isSending: chat.isSending,

packages/react/src/hooks/useConversationWith.ts

@@ -58,8 +58,6 @@ export type SwitchActiveDeviceOptions = {
 };
 
 type ConversationStateCommon = {
-  [Symbol.toStringTag]: "AgentSessionInstance",
-
   subtle: {
     emitter: TypedEventEmitter<ConversationCallbacks>;
     room: Room;
@@ -116,13 +114,13 @@ type ConversationActions = {
   end: () => Promise<void>;
 };
 
-export type ConversationInstance = (ConversationStateConnecting | ConversationStateConnected | ConversationStateDisconnected) & ConversationActions;
+export type UseConversationReturn = (ConversationStateConnecting | ConversationStateConnected | ConversationStateDisconnected) & ConversationActions;
 
 /**
  * AgentSession represents a connection to a LiveKit Agent, providing abstractions to make 1:1
  * agent/participant rooms easier to work with.
  */
-export function useConversationWith(agentToDispatch: string | RoomAgentDispatch | null, options: ConversationOptions): ConversationInstance {
+export function useConversationWith(agentToDispatch: string | RoomAgentDispatch | null, options: ConversationOptions): UseConversationReturn {
   const roomFromContext = useMaybeRoomContext();
   const room = useMemo(() => roomFromContext ?? options.room ?? new Room(), [roomFromContext, options.room]);
 
@@ -145,7 +143,7 @@ export function useConversationWith(agentToDispatch: string | RoomAgentDispatch
     };
   }, [options.tokenSource]);
 
-  const generateDerivedConnectionStateValues = useCallback(<State extends ConversationInstance["connectionState"]>(connectionState: State) => ({
+  const generateDerivedConnectionStateValues = useCallback(<State extends UseConversationReturn["connectionState"]>(connectionState: State) => ({
     isConnected: (
       connectionState === ConnectionState.Connected ||
       connectionState === ConnectionState.Reconnecting ||
@@ -209,8 +207,6 @@ export function useConversationWith(agentToDispatch: string | RoomAgentDispatch
 
   const conversationState = useMemo((): ConversationStateConnecting | ConversationStateConnected | ConversationStateDisconnected => {
     const common: ConversationStateCommon = {
-      [Symbol.toStringTag]: "AgentSessionInstance",
-
       subtle: {
         room,
         emitter,
@@ -275,13 +271,13 @@ export function useConversationWith(agentToDispatch: string | RoomAgentDispatch
     emitter.emit(ConversationEvent.ConnectionStateChanged, conversationState.connectionState);
   }, [emitter, conversationState.connectionState]);
 
-  const waitUntilConnectionState = useCallback(async (state: ConversationInstance["connectionState"], signal?: AbortSignal) => {
+  const waitUntilConnectionState = useCallback(async (state: UseConversationReturn["connectionState"], signal?: AbortSignal) => {
     if (conversationState.connectionState === state) {
       return;
     }
 
     return new Promise<void>((resolve, reject) => {
-      const onceEventOccurred = (newState: ConversationInstance["connectionState"]) => {
+      const onceEventOccurred = (newState: UseConversationReturn["connectionState"]) => {
         if (newState !== state) {
           return;
         }
@@ -393,6 +389,6 @@ export function useConversationWith(agentToDispatch: string | RoomAgentDispatch
   ]);
 }
 
-export function useConversation(options: ConversationOptions): ConversationInstance {
+export function useConversation(options: ConversationOptions): UseConversationReturn {
   return useConversationWith(null, options);
 }