Added useAsync and useForm

Author: aldrinpvincent

docs/docs/useAsync.md

@@ -0,0 +1,90 @@
+# useAsync
+
+A hook to manage state of any asynchronous operation. This hook can be used to manage `loading`, `data` and `error` states of an asynchronous operation. It is mainly used for data fetching, the first argument to the hook is the function that fetches and returns data, required options is the second argument and dependencies is the last argument.
+
+Only the most recent promise is considered in this hook, meaning you don't need to worry about any api race conditions could arise because of out of order responses from multiple api calls. In case of error the data will be of previous call or null.
+
+<pre>{`import { useAsync } from 'react-use-custom-hooks';`}</pre>
+
+### Usage example
+
+```typescript
+const [data, loading, error, refresh] = useAsync(() => fetchTodo(id), {}, [id]);
+```
+
+The fourth return value is a function to execute the operation again forcefully without any dependance change, like a refresh.
+
+```typescript
+<button onClick={() => refresh()}>Retry</button>
+```
+
+### Playground
+
+The component will fetch and show the todo based on the id, when ever the id changes the component will fetch the todo corresponding to the id. If there is any error in data fetching we will show the error message with a retry button. User can retry the last failed request by clicking the retry button.
+
+```jsx live
+function AsyncExample(props) {
+  const [id, setId] = React.useState(1);
+
+  // Move this to a service function
+  function fetchTodo(id) {
+    return fetch(`https://jsonplaceholder.typicode.com/todos/${id}`)
+      .then(response => response.json())
+      .then(json => json);
+  }
+
+  // if id changes, data will be fetched for the new id
+  const [data, loading, error, refresh] = useAsync(() => fetchTodo(id), {}, [
+    id,
+  ]);
+  if (loading) return <div>Loading...</div>;
+  if (error)
+    return (
+      <div>
+        Error: {error.message}
+        // User can retry on error without page refresh
+        <button onClick={() => refresh()}>Retry</button>
+      </div>
+    );
+
+  return (
+    <>
+      <p>
+        Id - <b>{id}</b>
+      </p>
+      <p>
+        Data - <b>{JSON.stringify(data)}</b>
+      </p>
+      <button onClick={() => setId(id => id + 1)}>++ Id</button>
+      <button
+        style={{ marginLeft: '10px' }}
+        onClick={() => setId(id => id - 1)}
+      >
+        -- Id
+      </button>
+    </>
+  );
+}
+```
+
+Only the most recent promise is considered in this hook, For example, in the above component there is a chance of race condition as depicted below.
+
+1.  Currently id is 123 and fetching details of id is 123
+2.  Then id changes to 465 while request for 123 is in progress and initiated request for 456
+3.  Response for 456 came back, state is updated with 456 data
+4.  Response for 123 came back, state is updated with 123 data
+
+    Here the UI will show 123 data even though the user selected 456 as id. This hook will take care of this issue by keeping only the most recent promise in the state by ignoring the current one if a new request is triggered.
+
+### API
+
+```typescript
+function useAsync(fn: () => Prm, options?: Options, deps = []);
+```
+
+#### Options
+
+| Property        | Description                  | Type       | Default |
+| --------------- | ---------------------------- | ---------- | ------- |
+| successCallback | Callback function on success | `Function` | -       |
+| errorCallback   | Callback function on failure | `Function` | -       |

docs/docs/useForm.md

@@ -0,0 +1,133 @@
+# useForm
+
+A hook to manage state of a form. This is an opinionated hook that will manage all internal state of a form and add `isValid` and `errorMessages` properties to each field for validation purpose, these properties are derived from the validator function provided to hook and can used to render error messages and to check if the form field is valid.
+
+<pre>{`import { useForm } from 'react-use-custom-hooks';`}</pre>
+
+### Usage example
+
+```typescript
+const [formData, setFormData] = useForm(initialState);
+```
+
+1. The initial state passed to this hook should be an object with key is the field name and value is an object with `value` and `validator` properties. The validator function should return `isValid` and `errorMessages` for the particular field upon invoking. For example,
+
+```js
+useForm({
+  name: {
+    value: '',
+    validator: value => {
+      return value.length > 0
+        ? {
+            isValid: true,
+            errorMessages: [],
+          }
+        : {
+            isValid: false,
+            errorMessages: ['Name is required'],
+          };
+    },
+  },
+});
+```
+
+2. This hook returns two values: form state and form change handler.
+3. The form state is an object will have the same structure as initialState with `isValid` and `errorMessages` properties added to every field.
+4. The form change handler is a function that takes a field name and a new value and updates the form state.
+5. For every call to change handler the validation function will be invoked with new value and form state will be updated accordingly.
+
+### Playground
+
+```jsx live
+function FormExample(props) {
+  const initialState = {
+    name: {
+      value: '',
+      validator: value => {
+        return value.length > 0
+          ? {
+              isValid: true,
+              errorMessages: [],
+            }
+          : {
+              isValid: false,
+              errorMessages: ['Name is required'],
+            };
+      },
+    },
+    age: {
+      value: '',
+      validator: value => {
+        if (!value) {
+          return {
+            isValid: false,
+            errorMessages: ['Age is required'],
+          };
+        }
+        if (value > 120) {
+          return {
+            isValid: false,
+            errorMessages: ['Age should be less than 120'],
+          };
+        }
+        if (value < 5) {
+          return {
+            isValid: false,
+            errorMessages: ['Age should be greater than 5'],
+          };
+        }
+        return {
+          isValid: true,
+          errorMessages: [],
+        };
+      },
+    },
+  };
+
+  const [formData, setFormData] = useForm(initialState); // All form updating and validation will be taken care by the hook
+  const { name, age } = formData;
+
+  const isValid = Object.values(formData).every(value => value.isValid);
+
+  return (
+    <form>
+      <label htmlFor="name">Name : </label>
+      <input
+        type="text"
+        value={name.value}
+        onChange={e => setFormData('name', e.target.value)}
+        style={{ border: `${!name.isValid ? '2px solid red' : ''}` }}
+      />
+      {name.errorMessages.length > 0 && (
+        <div style={{ color: 'red' }}>{name.errorMessages[0]}</div>
+      )}
+      <br />
+      <label htmlFor="age">Age : </label>
+      <input
+        type="number"
+        value={age.value}
+        onChange={e => setFormData('age', e.target.value)}
+        style={{ border: `${!age.isValid ? '2px solid red' : ''}` }}
+      />
+      {age.errorMessages.length > 0 && (
+        <div style={{ color: 'red' }}>{age.errorMessages[0]}</div>
+      )}
+      <br />
+      Form is <b>{isValid ? 'valid' : 'invalid'}</b>
+    </form>
+  );
+}
+```
+
+### API
+
+```typescript
+function useAsync(fn: () => any, options?: Options, deps = []);
+```
+
+#### Options
+
+| Property        | Description                  | Type       | Default |
+| --------------- | ---------------------------- | ---------- | ------- |
+| successCallback | Callback function on success | `Function` | -       |
+| errorCallback   | Callback function on failure | `Function` | -       |

docs/package.json

@@ -23,7 +23,7 @@
     "prism-react-renderer": "^1.2.1",
     "react": "^17.0.1",
     "react-dom": "^17.0.1",
-    "react-use-custom-hooks": "^0.2.1"
+    "react-use-custom-hooks": "^0.3.1"
   },
   "browserslist": {
     "production": [

docs/src/theme/ReactLiveScope/index.js

@@ -1,12 +1,12 @@
 
 import React from 'react';
-import { useDebounce, useSafeState, useIsMounted, usePrevious, useLegacyState, useTitle, useIsOnline, useIdle } from "react-use-custom-hooks";
+import { useDebounce, useSafeState, useIsMounted, usePrevious, useLegacyState, useTitle, useIsOnline, useIdle, useAsync, useForm } from "react-use-custom-hooks";
 
 // Add react-live imports you need here
 const ReactLiveScope = {
   React,
   ...React,
-  useDebounce, useSafeState, useIsMounted, usePrevious, useLegacyState, useTitle, useIsOnline, useIdle
+  useDebounce, useSafeState, useIsMounted, usePrevious, useLegacyState, useTitle, useIsOnline, useIdle, useAsync, useForm
 };
 
 export default ReactLiveScope;

package.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.2.1",
+  "version": "0.3.1",
   "license": "MIT",
   "main": "dist/index.js",
   "typings": "dist/index.d.ts",
@@ -73,4 +73,4 @@
     "typescript",
     "memory leak"
   ]
-}
+}

src/index.ts

@@ -6,6 +6,8 @@ import { useLegacyState } from './useLegacyState';
 import { useTitle } from './useTitle';
 import { useIsOnline } from './useIsOnline';
 import { useIdle } from './useIdle';
+import { useAsync } from './useAsync';
+import { useForm } from './useForm';
 
 export {
   useDebounce,
@@ -16,4 +18,6 @@ export {
   useTitle,
   useIsOnline,
   useIdle,
+  useAsync,
+  useForm,
 };

src/useAsync.ts

@@ -0,0 +1,86 @@
+import { useEffect, useReducer } from 'react';
+
+interface Options {
+  successCallback?: Function;
+  errorCallback?: Function;
+}
+
+const initialState = {
+  loading: true,
+  data: null,
+  error: null,
+};
+
+function reducer(state: any, action: { type: any; data: any }) {
+  switch (action.type) {
+    case 'loading':
+      return { ...state, loading: action.data };
+    case 'data':
+      return { ...state, data: action.data };
+    case 'error':
+      return { ...state, error: action.data };
+    default:
+      throw new Error();
+  }
+}
+
+function callFunction(fn: Function | undefined, params: any[]) {
+  if (fn && typeof fn === 'function') {
+    fn(...params);
+  }
+}
+
+/**
+ * @param {Function} fn - async function to be called
+ * @param {object} options - options for the hook
+ *      @param {Function} successCallback - callback to be called when promise resolves
+ *      @param {Function} errorCallback - callback to be called when promise rejects
+ * @param {Array} deps array of dependencies
+ * @returns {Array} - [loading, data, error, execute] - loading, data and error properties of the operation & a function to execute the operation again forcefully without any dependance change.
+ */
+export function useAsync(
+  fn: () => Promise<any>,
+  options?: Options,
+  deps: Array<any> = []
+): Array<any> {
+  const [state, dispatch] = useReducer(reducer, initialState);
+  const { loading, data, error } = state;
+
+  const { successCallback, errorCallback } = options || {};
+  const dependencyList = Array.isArray(deps) ? deps : [];
+
+  const execute = async (didCancel: boolean) => {
+    try {
+      if (!loading) dispatch({ type: 'loading', data: true });
+
+      const response = await fn();
+
+      if (!didCancel) {
+        dispatch({ type: 'data', data: response });
+        dispatch({ type: 'error', data: null });
+        callFunction(successCallback, [response]);
+      }
+    } catch (err) {
+      if (!didCancel) {
+        dispatch({ type: 'error', data: err });
+        callFunction(errorCallback, [err]);
+      }
+    } finally {
+      if (!didCancel) {
+        dispatch({ type: 'loading', data: false });
+      }
+    }
+  };
+
+  useEffect(() => {
+    let didCancel = false;
+
+    execute(didCancel);
+
+    return () => {
+      didCancel = true;
+    };
+  }, dependencyList);
+
+  return [data, loading, error, execute];
+}