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

• Vue.js
• React.js
• Alpine.js
• Svelte
• Angular
• Vanilla JS

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

1<template>
2    <div v-if="error">Whoops!</div>
3    <div v-else-if="isPending">loading...</div>
4    <div v-else-if="users.length === 0">no results...</div>
5    <UserList v-else :users="users" />
6</template>
7
8<script>
9export default {
10    data() {
11        return { users: [], isPending: true, error: null }
12    },
13    async created() {
14        const groupId = this.$route.params.groupId
15        this.isPending = true
16        try {
17            this.users = await fetch(`/api/${groupId}/users`).then(res => res.json())
18        } catch(error) {
19            this.error = error
20        }
21        this.isPending = false
22    }
23}
24</script>

With promistate

All state changes handled internally and exposed through a single object 👍.

1<template>
2    <div v-if="userPromise.error">Whoops!</div>
3    <div v-else-if="userPromise.isPending">loading...</div>
4    <div v-else-if="userPromise.isEmpty">no results...</div>
5    <UserList v-else :users="userPromise.value" />
6</template>
7
8<script>
9import promistate from 'promistate'
10
11export default {
12    data: ({
13        userPromise: promistate(groupId => fetch(`/api/${groupId}/users`).then(res => res.json()))
14    }),
15    created() {
16        this.userPromise.load(this.$route.params.groupId)
17    }
18}
19</script>

API

1import promistate from 'promistate'
2
3const userPromise = promistate(async function callback(id) {
4    return fetch('/api/user/' + id).then(res => res.json()) // any promise
5})
6
7// later...
8console.log(userPromise.value) // null
9await userPromise.load(1)
10console.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

1const calculator = promistate(async function callback(num1, num2) {
2    return num1 + num2
3})
4
5await 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

1import promistate, { PromistateStatus } from 'promistate'
2
3const userPromise = promistate(() => fetch('...'))
4
5if (await userPromise.load() === PromistateStatus.RESOLVED) {
6    console.log("It's resolved!", userPromise.value)
7}

Configurations

Pass configurations as the second argument

1import promistate from 'promistate'
2
3promistate(async function callback() {
4    return somethingAsync()
5}, { 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

1. Import usePromistate from promistate/lib/react
2. usePromistate returns a tuple with the first value holding the state, and the second value holding all methods to update the state

1import React from "react";
2import { usePromistate } from "promistate/lib/react";
3
4export default function App() {
5  const [todosPromise, todoActions] = usePromistate(somePromise);
6  // todosPromise.value, todosPromise.isPending, ...
7  // todoActions.load(), todoActions.reset(), todoActions.setValue('new Value')
8}

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.

1import promistate from 'promistate'
2
3promistate<string>(async function callback() {
4    return 'updated'
5}, { 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.

1import promistate from 'promistate'
2
3promistate(async function callback() {
4    const result = await fetchItems(this.value.pageToken)
5    return { pageToken: result.pageToken, items: this.items.concat(result.items) }
6}, {
7    defaultValue: { items: [], pageToken: null },
8    isEmpty: value => value.items.length < 1,
9})

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.

1import promistate from 'promistate'
2
3const promise = promistate(() => fetch('...'))
4
5promise.value // null
6promise.isEmpty // true
7
8promise.value = 2
9promise.isEmpty // false

If you use the react hook, do it like this instead:

1import { usePromistate } from 'promistate/lib/react'
2
3const [promise, actions] = usePromistate(() => fetch('...'))
4
5actions.setValue(2)

---

The same way you can also set the error programmatically.

1import promistate from 'promistate'
2
3const promise = promistate(() => fetch('...'))
4
5promise.error = new Error('internal error')

or with the react hook:

1import { usePromistate } from 'promistate/lib/react'
2
3const [promise, actions] = usePromistate(() => fetch('...'))
4
5actions.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.

1import promistate from 'promistate'
2import JSONFetch from 'fetch-me-json'
3
4const promise = promistate(() => JSONFetch.get('/api/...'))

Meta

Compile project

npm run build

Run tests

npm test