promistate
promistate copied to clipboard
Manage promises in UI libraries such as React.js, Vue.js, Angular, Svelte, Alpine.js, etc.
promistate
Easily manage promises in reactive JavaScript libraries and frameworks such as React.js, Vue.js, Angular, Svelte, Alpine.js, etc.
Installation
npm i promistate
Examples
Comparison (example with Vue.js)
Without 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>
With promistate
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>
API
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) |
load
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)
}
Configurations
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.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])
.
Typescript
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' })
FAQ
Can I use this for POST/PUT/DELETE requests as well?
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,
})
I need to manually change the value of a promise
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'))
I need to make a lot of ajax requests, is there something better than regular fetch
?
Sure, I personally use fetch-me-json.
import promistate from 'promistate'
import JSONFetch from 'fetch-me-json'
const promise = promistate(() => JSONFetch.get('/api/...'))
Meta
Compile project
npm run build
Run tests
npm test