Added usePromiseEffect() React hook

Author: Gijs Nieuwenhuis

README.md

@@ -30,6 +30,7 @@ A library containing javascript utilities that we until now often copy between p
         -   [`useStateWithRef`](#usestatewithref)
         -   [`useScrollToTopOnDependencyChange`](#usescrolltotopondependencychange)
         -   [`useTrackingProps`](#usetrackingprops)
+        -   [`usePromiseEffect`](#usepromiseeffect)
 -   [Storage](#storage)
     -   [`localStorage`](#localstorage)
     -   [`sessionStorage`](#sessionstorage)
@@ -425,6 +426,50 @@ const PreorderSubmitButton: React.FC<Props> = (subscribeToNewsletter) => {
 };
 ```
 
+### `usePromiseEffect`
+
+When working with promises in `useEffect()` you have many things to take into account:
+
+-   What to render when the promise is pending
+-   How to catch errors and render your error notification
+-   What to render when the value is resolved
+
+This hook helps you with the status changes and reduces the number of re-renders required to get there.
+
+Usage:
+
+```tsx
+import usePromiseEffect from '@freshheads/javascript-essentials/build/react/hooks/usePromiseEffect';
+
+type Props = {
+    page: number
+}
+
+const ArticleOverview: React.FC<Props> => ({ page }) => {
+    const { value: articles, pending, error } = usePromiseEffect<Article[]>(() => fetchArticles(), [page]);
+
+    if (pending) {
+        return <Loader />;
+    }
+
+    if (error) {
+        return <Error message={error.message} />;
+    }
+
+    if (!value) {
+        throw new Error('Value should be available at this point');
+    }
+
+    return (
+        <div>
+            { state.value.map(article => (
+                <Article data={article} key={article.id} />
+            )) }
+        </div>
+    )
+}
+```
+
 ## Routing
 
 ### `createPathFromRoute`

src/react/hooks/__tests__/usePromiseEffect.test.ts

@@ -0,0 +1,85 @@
+import { EffectExecutor } from './../usePromiseEffect';
+import { renderHook, act } from '@testing-library/react-hooks';
+import usePromiseEffect, { Status, Response } from '../usePromiseEffect';
+
+describe('usePromiseEffect', () => {
+    describe('When pending', () => {
+        it('should return the pending state', (done) => {
+            const executeEffect: EffectExecutor<string> = async () => {
+                return new Promise((resolve) => {
+                    setTimeout(() => {
+                        resolve('hallo');
+                    }, 200);
+                });
+            };
+
+            const { result } = renderHook<{}, Response<string>>(() =>
+                usePromiseEffect<string>(executeEffect, [])
+            );
+
+            expect(result.current).toEqual({
+                pending: true,
+                error: null,
+                value: null,
+            });
+
+            done();
+        });
+    });
+
+    describe('When successful', () => {
+        it('should return the fulffilled state', async (done) => {
+            const executeEffect: EffectExecutor<string> = async () => {
+                return new Promise((resolve) => {
+                    setTimeout(() => {
+                        resolve('hallo');
+                    }, 200);
+                });
+            };
+
+            const { result, waitForNextUpdate } = renderHook<
+                {},
+                Response<string>
+            >(() => usePromiseEffect<string>(executeEffect, []));
+
+            await waitForNextUpdate();
+
+            expect(result.current).toEqual({
+                pending: false,
+                value: 'hallo',
+                error: null,
+            });
+
+            done();
+        });
+    });
+
+    describe('When an error occurs', () => {
+        it('should return the error state', async (done) => {
+            const error = new Error('Some test error');
+
+            const executeEffect: EffectExecutor<string> = async () => {
+                return new Promise((_resolve, reject) => {
+                    setTimeout(() => {
+                        reject(error);
+                    }, 200);
+                });
+            };
+
+            const { result, waitForNextUpdate } = renderHook<
+                {},
+                Response<string>
+            >(() => usePromiseEffect<string>(executeEffect, []));
+
+            await waitForNextUpdate();
+
+            expect(result.current).toEqual({
+                error,
+                value: null,
+                pending: false,
+            });
+
+            done();
+        });
+    });
+});

src/react/hooks/usePromiseEffect.ts

@@ -0,0 +1,65 @@
+import { DependencyList, useEffect, useState } from 'react';
+
+export enum Status {
+    Pending = 'pending',
+    Fulfilled = 'fullfiled',
+    Rejected = 'rejected',
+}
+
+export type PendingState = { status: Status.Pending; value: null; error: null };
+
+export type RejectedState = {
+    status: Status.Rejected;
+    value: null;
+    error: Error;
+};
+
+export type FulfilledState<T> = {
+    status: Status.Fulfilled;
+    value: T;
+    error: null;
+};
+
+export type PromiseState<T> = PendingState | FulfilledState<T> | RejectedState;
+
+export type EffectExecutor<T> = () => Promise<T>;
+
+export type Response<T> = {
+    value: T | null;
+    pending: boolean;
+    error: Error | null;
+};
+
+export default function usePromiseEffect<T>(
+    executeEffect: EffectExecutor<T>,
+    deps: DependencyList,
+    cleanup?: () => void
+): Response<T> {
+    const [state, setState] = useState<PromiseState<T>>({
+        status: Status.Pending,
+        value: null,
+        error: null,
+    });
+
+    useEffect(() => {
+        executeEffect()
+            .then((value) => {
+                setState({
+                    status: Status.Fulfilled,
+                    value,
+                    error: null,
+                });
+            })
+            .catch((error) =>
+                setState({ status: Status.Rejected, value: null, error })
+            );
+
+        return cleanup;
+    }, deps);
+
+    return {
+        value: state.value,
+        pending: state.status === Status.Pending,
+        error: state.error,
+    };
+}