Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/slorber/awesome-debounce-promise
Debounce your API calls easily and stay in promised land.
https://github.com/slorber/awesome-debounce-promise
List: awesome-debounce-promise
callback debounce debounce-promise debouncing-functions react react-hooks throttle
Last synced: 7 days ago
JSON representation
Debounce your API calls easily and stay in promised land.
- Host: GitHub
- URL: https://github.com/slorber/awesome-debounce-promise
- Owner: slorber
- Created: 2018-09-13T12:08:27.000Z (over 6 years ago)
- Default Branch: master
- Last Pushed: 2021-10-06T10:32:49.000Z (about 3 years ago)
- Last Synced: 2024-11-30T15:08:15.943Z (14 days ago)
- Topics: callback, debounce, debounce-promise, debouncing-functions, react, react-hooks, throttle
- Language: TypeScript
- Homepage: https://sebastienlorber.com
- Size: 360 KB
- Stars: 392
- Watchers: 5
- Forks: 9
- Open Issues: 5
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# Awesome Debounce Promise
[](https://www.npmjs.com/package/awesome-debounce-promise)
[](https://travis-ci.com/slorber/awesome-debounce-promise)
Debounce your async calls with **React** in mind.
- No callback hell of lodash/underscore
- Handle concurrent requests nicely (only use last request's response)
- Typescript support (native and well typed)
- React in mind, but can be used in other contexts (no dependency)
Read also [this famous SO question](https://stackoverflow.com/a/28046731/82609) about debouncing with React.
---
# Sponsor
**[ThisWeekInReact.com](https://thisweekinreact.com)**: the best newsletter to stay up-to-date with the React ecosystem:
[](https://thisweekinreact.com)
---
# Install
`yarn add awesome-debounce-promise`
`npm install awesome-debounce-promise --save`
```jsx harmony
import AwesomeDebouncePromise from 'awesome-debounce-promise';
const asyncFunction = () => fetch('/api');
const asyncFunctionDebounced = AwesomeDebouncePromise(
asyncFunction,
500,
options,
);
asyncFunctionDebounced().then(console.log); // no request fired, promise will never resolve
asyncFunctionDebounced().then(console.log); // no request fired, promise will never resolve
asyncFunctionDebounced().then(console.log); // request fired, promise will resolve with response
```
For Typescript, you need the compiler option `"esModuleInterop": true`
# Usecases
## Debouncing a search input (with React class)
```jsx harmony
const searchAPI = text => fetch('/search?text=' + encodeURIComponent(text));
const searchAPIDebounced = AwesomeDebouncePromise(searchAPI, 500);
class SearchInputAndResults extends React.Component {
state = {
text: '',
results: null,
};
handleTextChange = async text => {
this.setState({ text, results: null });
const result = await searchAPIDebounced(text);
this.setState({ result });
};
componentWillUnmount() {
this.setState = () => {};
}
}
```
When calling `debouncedSearchAPI`:
- it will debounce the api calls. The API will only be called when user stops typing
- each call will return a promise
- only the promise returned by the last call will resolve, which will prevent the concurrency issues
- there will be at most a single `this.setState({ result });` call per api call
## Debouncing a search input (with React hooks)
I recommend solving this problem with [react-async-hook](https://github.com/slorber/react-async-hook), which plays well with `awesome-debounce-promise`. You'll find more informations on `react-async-hook` readme and runnable examples.
```tsx
const useSearchStarwarsHero = () => {
// Handle the input text state
const [inputText, setInputText] = useState('');
// Debounce the original search async function
const debouncedSearchStarwarsHero = useConstant(() =>
AwesomeDebouncePromise(searchStarwarsHero, 300)
);
const search = useAsync(debouncedSearchStarwarsHero,[inputText]);
// Return everything needed for the hook consumer
return {
inputText,
setInputText,
search,
};
};
```
## Debouncing the background saving of some form inputs
```jsx harmony
const saveFieldValue = (fieldId, fieldValue) =>
fetch('/saveField', {
method: 'PUT',
body: JSON.stringify({ fieldId, fieldValue }),
});
const saveFieldValueDebounced = AwesomeDebouncePromise(
saveFieldValue,
500,
// Use a key to create distinct debouncing functions per field
{ key: (fieldId, text) => fieldId },
);
class SearchInputAndResults extends React.Component {
state = {
value1: '',
value2: '',
};
onFieldTextChange = async (fieldId, fieldValue) => {
this.setState({ [fieldId]: fieldValue });
await saveFieldValueDebounced(fieldId, fieldValue);
};
render() {
const { value1, value2 } = this.state;
return (
onFieldTextChange(1, e.target.value)}
/>
onFieldTextChange(2, e.target.value)}
/>
);
}
}
```
Thanks to the `key` feature, the 2 fields will be debounced independently from each others. In practice, one debounced function is created for each key.
# Options
```jsx harmony
const DefaultOptions = {
// One distinct debounced function is created per key and added to an internal cache
// By default, the key is null, which means that all the calls
// will share the same debounced function
key: (...args) => null,
// By default, a debounced function will only resolve
// the last promise it returned
// Former calls will stay unresolved, so that you don't have
// to handle concurrency issues in your code
// Setting this to false means all returned promises will resolve to the last result
onlyResolvesLast: true,
};
```
Other debouncing options are available and provided by an external low-level library: [debounce-promise](https://github.com/bjoerge/debounce-promise)
# FAQ
### How can I cancel the debouncing?
You can easily add promise cancellation support to this lib with [awesome-imperative-promise](https://github.com/slorber/awesome-imperative-promise), lib that is already used internally.
### Why is my debouncing function always firing and is not debounced?
The debouncing function returned by the lib is stateful. If you want deboucing to work fine, make sure to avoid recreating this function everytime. This is the same behavior as regular callback-based debouncing functions.
Instead of this:
```js
handleTextChange = async text => {
const searchAPI = text => fetch('/search?text=' + encodeURIComponent(text));
const searchAPIDebounced = AwesomeDebouncePromise(searchAPI, 500);
this.setState({ text, results: null });
const result = await searchAPIDebounced(text);
this.setState({ result });
};
```
Do this:
```js
const searchAPI = text => fetch('/search?text=' + encodeURIComponent(text));
const searchAPIDebounced = AwesomeDebouncePromise(searchAPI, 500);
handleTextChange = async text => {
this.setState({ text, results: null });
const result = await searchAPIDebounced(text);
this.setState({ result });
};
```
# Dependencies
This library is a combination of multiple low-level tiny microlibs:
- [debounce-promise](https://github.com/bjoerge/debounce-promise)
- [awesome-only-resolves-last-promise](https://github.com/slorber/awesome-only-resolves-last-promise)
- [awesome-imperative-promise](https://github.com/slorber/awesome-imperative-promise)
# Hire a freelance expert
Looking for a React/ReactNative freelance expert with more than 5 years production experience?
Contact me from my [website](https://sebastienlorber.com/) or with [Twitter](https://twitter.com/sebastienlorber).