Easily manage promises in reactive JavaScript libraries and frameworks such as React.js, Vue.js, Angular, Svelte, Alpine.js, etc.
npm i promistate
- Need to manage promise result, error and pending status all as separate state
- Need to manage a computed field to determine whether the result is empty or not
- Need to write custom logic to ignore stale promises / cancel promises
- results in bloated code as all of this is repeated in many components
<template>
<div v-if="error">Whoops!</div>
<div v-else-if="isPending">loading...</div>
<div v-else-if="users.length === 0">no results...</div>
<UserList v-else :users="users" />
</template>
<script>
export default {
data() {
return { users: [], isPending: true, error: null }
},
async created() {
const groupId = this.$route.params.groupId
this.isPending = true
try {
this.users = await fetch(`/api/${groupId}/users`).then(res => res.json())
} catch(error) {
this.error = error
}
this.isPending = false
}
}
</script>
All state changes handled internally and exposed through a single object 👍.
<template>
<div v-if="userPromise.error">Whoops!</div>
<div v-else-if="userPromise.isPending">loading...</div>
<div v-else-if="userPromise.isEmpty">no results...</div>
<UserList v-else :users="userPromise.value" />
</template>
<script>
import promistate from 'promistate'
export default {
data: ({
userPromise: promistate(groupId => fetch(`/api/${groupId}/users`).then(res => res.json()))
}),
created() {
this.userPromise.load(this.$route.params.groupId)
}
}
</script>
import promistate from 'promistate'
const userPromise = promistate(async function callback(id) {
return fetch('/api/user/' + id).then(res => res.json()) // any promise
})
// later...
console.log(userPromise.value) // null
await userPromise.load(1)
console.log(userPromise.value) // { id: 1, name: '...' }
The callback passed into promistate
gets executed once you call the "load" method.
Calling "promistate()" immediately returns an object that has the following properties.
(See below for react hook example)
field | description |
---|---|
load | A method to call the previously passed in callback. Arguments get propogated to callback |
value | Holds the resolved promise result |
isPending | Defines if promise is currently pending |
isDelayOver | Defines if promise is currently pending and the given delay (see configurations) has elapsed. |
timesSettled | counts how many times a promise was settled. Sometimes you want to wait until a promise was settled |
isEmpty | Defines if there is a result. Conveniently switches to false when promise is pending. isEmpty is true when the result is an empty array, empty object, null or undefined |
error | Error object in case promise was rejected |
reset | A method to reset all state (value, isEmpty, error, isPending) |
You can pass in arguments as needed
const calculator = promistate(async function callback(num1, num2) {
return num1 + num2
})
await calculator.load(1, 2)
"load" returns a status message about the promise. This can be either
- RESOLVED
- ERROR
- IGNORED (see configurations below)
This can be useful if you have to do more work after loading a promise. Note how there is no need to reach for this in the example at the top.
To avoid hardcoding these, you can import "PromistateStatus" from the library
import promistate, { PromistateStatus } from 'promistate'
const userPromise = promistate(() => fetch('...'))
if (await userPromise.load() === PromistateStatus.RESOLVED) {
console.log("It's resolved!", userPromise.value)
}
Pass configurations as the second argument
import promistate from 'promistate'
promistate(async function callback() {
return somethingAsync()
}, { catchErrors: false, defaultValue: 42 })
key | type | default | use case |
---|---|---|---|
catchErrors | boolean |
true | You already use something like an ErrorBoundary component for catching errors |
defaultValue | any |
null | You already have a value at hand, or want to default it to an empty array, object, etc. |
ignoreStaleLoad | boolean |
false | If you "load" while there is already a promise pending, this will ignore any stale promise results. By calling "reset" you can also cancel promises this way. |
ignoreLoadWhenPending | boolean |
false | Prevent an event being fired twice e.g. when clicking a button. With this boolean set, while the first promise is still pending, subsequent loads would be ignored (not deferred!). When a subsequent load gets ignored, the "load" method returns the status "IGNORED" |
delay | number |
200 | Specifies after how many ms isDelayOver will be set to true. This is useful to avoid flashing loading spinners for fast requests. |
isEmpty | Function |
undefined | Say, the result is { page: 1, items: [] } , the default "isEmpty" would always evaluate to false since a filled object is considered not empty. You can tweak the check like this: { isEmpty: value => value.items.length < 1 } |
listen | Function |
undefined | Listen to any state changes. Useful for integrations in libraries like Svelte or React.js |
Usage with react differs in two ways
- Import
usePromistate
frompromistate/lib/react
usePromistate
returns a tuple with the first value holding the state, and the second value holding all methods to update the state
import React from "react";
import { usePromistate } from "promistate/lib/react";
export default function App() {
const [todosPromise, todoActions] = usePromistate(somePromise);
// todosPromise.value, todosPromise.isPending, ...
// todoActions.load(), todoActions.reset(), todoActions.setValue('new Value')
}
You can pass promistate options as the second argument usePromistate(somePromise, { defaultValue: "" })
,
and promise depedencies as the third argument usePromistate(somePromise, { }, [dep1, dep2])
.
To type the result of the promise you can make use of generics.
import promistate from 'promistate'
promistate<string>(async function callback() {
return 'updated'
}, { defaultValue: 'initial' })
Absolutely.
an API call returns a page token which I need the next time I make a request to fetch the next page, I also need to append the data to the previous result
As long as you don't use arrow functions you can access the state using this
.
import promistate from 'promistate'
promistate(async function callback() {
const result = await fetchItems(this.value.pageToken)
return { pageToken: result.pageToken, items: this.items.concat(result.items) }
}, {
defaultValue: { items: [], pageToken: null },
isEmpty: value => value.items.length < 1,
})
Often times you want to reset the promise to its initial state. For this you can use the "reset" method.
But of course you can still mutate the value directly.
import promistate from 'promistate'
const promise = promistate(() => fetch('...'))
promise.value // null
promise.isEmpty // true
promise.value = 2
promise.isEmpty // false
If you use the react hook, do it like this instead:
import { usePromistate } from 'promistate/lib/react'
const [promise, actions] = usePromistate(() => fetch('...'))
actions.setValue(2)
The same way you can also set the error programmatically.
import promistate from 'promistate'
const promise = promistate(() => fetch('...'))
promise.error = new Error('internal error')
or with the react hook:
import { usePromistate } from 'promistate/lib/react'
const [promise, actions] = usePromistate(() => fetch('...'))
actions.setError(new Error('internal error'))
Sure, I personally use fetch-me-json.
import promistate from 'promistate'
import JSONFetch from 'fetch-me-json'
const promise = promistate(() => JSONFetch.get('/api/...'))
npm run build
npm test