https://github.com/termosa/use-request
Make it easy to use async functions with state and memoization
https://github.com/termosa/use-request
Last synced: 9 months ago
JSON representation
Make it easy to use async functions with state and memoization
- Host: GitHub
- URL: https://github.com/termosa/use-request
- Owner: termosa
- License: mit
- Created: 2022-01-21T06:51:02.000Z (over 4 years ago)
- Default Branch: master
- Last Pushed: 2024-06-09T12:59:26.000Z (about 2 years ago)
- Last Synced: 2024-12-13T00:32:46.250Z (over 1 year ago)
- Language: TypeScript
- Size: 3.25 MB
- Stars: 2
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# `useRequest(cb, [...args])`
> Finally, easy way to use async functions in React
[](https://www.npmjs.com/package/use-request)
Call, observe, and persist the result of your async functions with the ease!
See how it works:
```tsx
const RandomNumberGenerator = () => {
const request = useRequest(() => api('/random-number'))
return (
{request.value && Here is your random number: {request.value}
}
{request.error && Request failed due to: {request.error}
}
)
}
```
Now, step-by-step:
## Install
```bash
npm install --save use-request
```
## Usage
```tsx
import useRequest, { UseRequestStatus } from 'use-request'
const Example = () => {
const request = useRequest(
callback, // Async function (can be sync if needed)
[] // Optional arguments list. The callback will be called immediately if this is set
)
// Results
request.value // Last result of the callback
request.error // Last error thrown from the callback
// Methods
request.execute(...callbackArgs) // Proxy to trigger the callback()
request.reset() // Drop the state and cancel ongoing requests
// Lifecycle
request.idle // True, when request is not initialized or was reset, use for initial screen
request.pending // True, when the request is ongoing, use to show spinners, disabled forms, etc.
request.completed // True, when the request is successfully resolved
request.failed // True, when the request is rejected
request.status // Value of UseRequestStatus enum, helpful for tracking request status
// ...
}
```
### The simplest usage sample
```tsx
function SaveButton() {
const request = useRequest(() => api('/save'))
return save
}
```
### Make it run instantly
```tsx
function useUserData() {
const request = useRequest(() => api('/user'), [])
return request.value
}
```
### Configure it
```tsx
function useUserData(userId) {
const request = useRequest((id) => api(`/user/${id}`), [userId])
return request.value
}
```
### Use arguments with `execute()`
```tsx
const RemoveButton = (id) => {
const request = useRequest((itemId) => api.delete(`/items/${itemId}`))
return request.execute(id)}>remove
}
```
### Observe the state
```tsx
const Button = ({ label, callback }) => {
const request = useRequest(callback)
return (
{label}
)
}
```
## More Examples
### Using it for a single async function
[Source code](https://github.com/termosa/use-request/blob/master/example/src/SingleFunctionExample.js)
```tsx
const generateNumber = (max) =>
new Promise((resolve, reject) => {
if (max > 0) setTimeout(resolve, 2e3, Math.round(Math.random() * max))
else setTimeout(reject, 2e3, 'Max value must be greater than zero')
})
const defaultMax = 100
const SingleFunctionExample = () => {
const [max, setMax] = React.useState('')
const { value, error, pending } = useRequest(
generateNumber, // Async function that returns promise
[max ? +max : defaultMax] // Initial arguments
)
return (
setMax(e.target.value)} />
{pending ? processing : null}
{value !== undefined ? Last result: {value} : null}
{error ? Error: {error} : null}
)
}
```
### Create a model hook with auto-reloading
[Source code](https://github.com/termosa/use-request/blob/master/example/src/MultipleFunctionsExample.js)
```tsx
const useResources = () => {
const { execute: reload, value: resources, status } = useRequest(api.get, [])
const { execute: create } = useRequest((resource) => api.post(resource).then(reload))
const { execute: remove } = useRequest((id) => api.delete(id).then(reload))
return { resources, status, create, remove }
}
const MultipleFunctionsExample = () => {
/** @type {React.MutableRefObject} */
const resourceLabelRef = useRef(null)
const { resources, status, create, remove } = useResources()
const onSubmit = (e) => {
e.preventDefault()
if (!resourceLabelRef.current) return
create({ label: resourceLabelRef.current.value })
resourceLabelRef.current.value = ''
}
return (
{!resources && status === UseRequestStatus.Pending ?
Loading...
: null}
{resources ? (
{resources.map((res) => (
-
{res.label} remove(res.id)} value="remove" />
))}
) : null}
)
}
```
## License
MIT © [termosa](https://me.st)
---
This hook is created using [create-react-hook](https://github.com/hermanya/create-react-hook).