cached-effect

💥 React effect manager

Manage effects in React using hooks. Create cached effects from async functions and handle them with useCache hook. Run your effects in order to update cache. It supports Concurrent Mode and rerenders components only when needed.

This package is very lightweight: 1.5kb minified (without react)

Installation

npm install cached-effect

or yarn

yarn add cached-effect

Usage

import { createEffect, useCache } from 'cached-effect'

Wrap a function that returns a promise in createEffect to create an effect:

const effect = createEffect(async () => { /* do something */ })
 
// or
 
const fetchUsers = createEffect(({ organizationId }) => axios
  .get(`/organizations/${organizationId}/users`)
  .then(getUsers)
)

Then use it in useCache hook in your React component:

const [users, usersError, usersLoading] = useCache(fetchUsers)

It returns an array of [result, error, pending]. These values stay the same until you run your effect. Use array destructuring to get values that you need.

Running effects

In order to update the cache you need to run your effect. For example, in useEffect hook inside of your component:

useEffect(() => {
  fetchUsers({ organizationId }) // or fetchUsers.once (see below)
}, [])

In this case users will be fetched after the component mounts. But it's useful to run your effect only once, for instance, when you have many mounting components using this effect:

useEffect(() => {
  fetchUsers.once({ organizationId })
}, [])

You can also refetch users or rerun any effect manually just calling it:

<Button
  type='button'
  onClick={() => fetchUsers({ organizationId })}
/>

React Hooks

useCache hook

Takes an effect and returns an array of [result, error, pending]:

const [result, error, pending] = useCache(effect)

It is equal to [undefined, null, false] by default and updates its values when you call the effect

usePending hook

Returns a pending status of your effect (true/false):

const pending = usePending(effect)

You can use it to show a spinner, for example. It is a syntactic sugar over useCache hook (the third value)

useError hook

Returns an error of your effect (or null):

const error = useError(effect)

You can use it if you need to show only an error of your effect somewhere. It is a syntactic sugar over useCache hook (the second value)

Effect

Effect is a container for an async function. It can be safely used in place of the original async function.

createEffect(handler)

Creates and returns an effect

effect(payload)

Runs an effect. Returns promise

effect.once(payload)

Runs an effect only once. Returns original promise on a repeated call

effect.watch(watcher)

Listens to the effect and calls watcher. Watcher receives payload and promise.

Returns back an unsubscribe function.

effect.use(handler)

Injects an async function into effect (can be called multiple times). This is useful for mocking API calls, testing etc.

effect.use.getCurrent()

Returns current effect handler

Promise

Promise is a container for async value. It has some additional methods.

promise.cache()

Returns a result synchronously if promise is completed successfully.

There will be no promise.cache method if promise is rejected!

promise.failure()

Returns an error synchronously if promise failed.

There will be no promise.failure method if promise fulfills!

promise.anyway()

Returns a promise that will be resolved anyway (aka .finally)

Tip

If you found this hook useful, please star this package on GitHub ★

Author

@doasync

Credits

This package was inspired by Effector library (from @ZeroBias). Effector is a reactive state manager, which has stores, events and effects as well as other useful features for managing state. This package is not compatible with effector effects right now.