add useCallableFunctionResponse (#449)

Author: jhuleatt

docs/reference/README.md

@@ -14,7 +14,8 @@
   * [Show a single document](#show-a-single-document)
   * [Show a list of data (collection)](#show-a-list-of-data-collection)
 - [Cloud Functions](#cloud-functions)
-  * [Call a function](#call-a-function)
+  * [Call a function based on user interaction](#call-a-function-based-on-user-interaction)
+  * [Call a function on render](#call-a-function-on-render)
 - [Realtime Database](#realtime-database)
   * [Show an object](#show-an-object)
   * [Show a list of data](#show-a-list-of-data)
@@ -304,7 +305,7 @@ function FavoriteAnimals() {
 
 The following samples assume that `FirebaseAppProvider` and `FunctionsProvider` components exist higher up the component tree.
 
-### Call a function
+### Call a function based on user interaction
 
 ```jsx
 function Calculator() {
@@ -327,6 +328,18 @@ function Calculator() {
 }
 ```
 
+### Call a function on render
+
+If you want to call a function when a component renders, instead of in response to user interaction, you can use the `useCallableFunctionResponse` hook.
+
+```jsx
+function LikeCount({ videoId }) {
+  const { status, data: likeCount } = useCallableFunctionResponse('countVideoLikes', { data: { videoId: videoId } });
+
+  return <span>This video has {status === 'loading' ? '...' : likeCount} likes</span>;
+}
+```
+
 ## Realtime Database
 
 The following samples assume that `FirebaseAppProvider` and `RealtimeDatabaseProvider` components exist higher up the component tree.

docs/reference/modules/functions.md

@@ -1,7 +1,7 @@
 import 'firebase/storage';
 import * as React from 'react';
 import { useState } from 'react';
-import { useFirebaseApp, FunctionsProvider, useFunctions } from 'reactfire';
+import { useFirebaseApp, FunctionsProvider, useFunctions, useCallableFunctionResponse } from 'reactfire';
 import { CardSection } from '../display/Card';
 import { LoadingSpinner } from '../display/LoadingSpinner';
 import { WideButton } from '../display/Button';
@@ -13,11 +13,12 @@ function UpperCaser() {
   const [uppercasedText, setText] = useState<string>('');
   const [isUppercasing, setIsUppercasing] = useState<boolean>(false);
 
+  const greetings = ['Hello World', 'yo', `what's up?`];
+  const textToUppercase = greetings[Math.floor(Math.random() * greetings.length)];
+
   async function handleButtonClick() {
     setIsUppercasing(true);
 
-    const greetings = ['Hello World', 'yo', `what's up?`];
-    const textToUppercase = greetings[Math.floor(Math.random() * greetings.length)];
     const { data: capitalizedText } = await capitalizeTextRemoteFunction({ text: textToUppercase });
     setText(capitalizedText);
 
@@ -27,11 +28,23 @@ function UpperCaser() {
   return (
     <>
       <WideButton label="Uppercase some text" onClick={handleButtonClick} />
-      {isUppercasing ? <LoadingSpinner /> : <span>{uppercasedText}</span>}
+      {isUppercasing ? <LoadingSpinner /> : <span>{uppercasedText || `click the button to capitalize "${textToUppercase}"`}</span>}
     </>
   );
 }
 
+function UpperCaserOnRender() {
+  const greetings = ['Hello World', 'yo', `what's up?`];
+  const textToUppercase = greetings[Math.floor(Math.random() * greetings.length)];
+  const { status, data: uppercasedText } = useCallableFunctionResponse<{ text: string }, string>('capitalizeText', { data: { text: textToUppercase } });
+
+  if (status === 'loading') {
+    return <LoadingSpinner />;
+  }
+
+  return <span>{uppercasedText}</span>;
+}
+
 export function Functions() {
   const app = useFirebaseApp();
 
@@ -40,6 +53,9 @@ export function Functions() {
       <CardSection title="Call a cloud function">
         <UpperCaser />
       </CardSection>
+      <CardSection title="Call a function on render">
+        <UpperCaserOnRender />
+      </CardSection>
     </FunctionsProvider>
   );
 }

docs/reference/modules/index.md

@@ -0,0 +1,28 @@
+import { httpsCallable as rxHttpsCallable } from 'rxfire/functions';
+import { ReactFireOptions, useObservable, ObservableStatus } from './';
+import { useFunctions } from '.';
+
+import type { HttpsCallableOptions } from 'firebase/functions';
+
+/**
+ * Calls a callable function.
+ *
+ * @param functionName - The name of the function to call
+ * @param options
+ */
+export function useCallableFunctionResponse<RequestData, ResponseData>(
+  functionName: string,
+  options?: ReactFireOptions<ResponseData> & {
+    httpsCallableOptions?: HttpsCallableOptions;
+    data?: RequestData;
+  }
+): ObservableStatus<ResponseData> {
+  const functions = useFunctions();
+  const observableId = `functions:callableResponse:${functionName}:${JSON.stringify(options?.data)}:${JSON.stringify(options?.httpsCallableOptions)}`;
+  const obsFactory = rxHttpsCallable<RequestData, ResponseData>(functions, functionName, options?.httpsCallableOptions);
+
+  //@ts-expect-error because RxFire doesn't make data optional. Remove when https://github.com/FirebaseExtended/rxfire/pull/34 is released.
+  const observable$ = obsFactory(options?.data);
+
+  return useObservable(observableId, observable$, options);
+}

docs/use.md

@@ -52,6 +52,7 @@ export * from './auth';
 export * from './database';
 export * from './firebaseApp';
 export * from './firestore';
+export * from './functions';
 export * from './performance';
 export * from './remote-config';
 export * from './storage';

example/withoutSuspense/Functions.tsx

@@ -1,9 +1,10 @@
 import { initializeApp } from 'firebase/app';
 import { getFunctions, connectFunctionsEmulator, httpsCallable } from 'firebase/functions';
 import { FunctionComponent } from 'react';
-import { FirebaseAppProvider, FunctionsProvider, useFunctions } from '..';
+import { FirebaseAppProvider, FunctionsProvider, useFunctions, useCallableFunctionResponse } from '..';
 import { baseConfig } from './appConfig';
 import { renderHook } from '@testing-library/react-hooks';
+import { randomString } from './test-utils';
 import * as React from 'react';
 
 describe('Functions', () => {
@@ -25,12 +26,25 @@ describe('Functions', () => {
       expect(functionsInstance).toBeDefined();
 
       // `capitalizeText` function is in `functions/index.js`
-      const capitalizeTextRemoteFunction = httpsCallable(functionsInstance, 'capitalizeText');
+      const capitalizeTextRemoteFunction = httpsCallable<{ text: string }, string>(functionsInstance, 'capitalizeText');
       const testText = 'Hello World';
 
       const { data: capitalizedText } = await capitalizeTextRemoteFunction({ text: testText });
 
       expect(capitalizedText).toEqual(testText.toUpperCase());
     });
   });
+
+  describe('useCallableFunctionResponse', () => {
+    it('calls a function on render', async () => {
+      const testText = randomString();
+      const { result, waitFor } = renderHook(() => useCallableFunctionResponse<{ text: string }, string>('capitalizeText', { data: { text: testText } }), {
+        wrapper: Provider,
+      });
+
+      await waitFor(() => result.current.status === 'success');
+
+      expect(result.current.data).toEqual(testText.toUpperCase());
+    });
+  });
 });