# react-optimist

> Optimistic UI for React using the new Context API.

Latest version **0.1.5** (published 2018-10-15) · MIT license · 0 weekly downloads

## Install

```sh
npm install react-optimist
pnpm add react-optimist
yarn add react-optimist
bun add react-optimist
```

## Health

**Score 20/100 (F)** — status: abandoned.

Positive: esm support; no vulnerabilities.

Warnings: low downloads; no types; pre 1.0.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.1.5 |
| Published | 2018-10-15 |
| First published | 2018-05-18 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | ESM + CommonJS |
| Dependencies | 1 |
| Unpacked size | 53.3 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 2 |
| Author | Kasper Pihl Tornoe |
| Maintainers | kasperpihl |
| Keywords | react, optimistic, ui |

## Links

- npm: https://www.npmjs.com/package/react-optimist
- Repository: https://github.com/swipesapp/react-optimist
- Homepage: https://github.com/swipesapp/react-optimist#readme
- Issues: https://github.com/swipesapp/react-optimist/issues
- npm.io page: https://npm.io/package/react-optimist

## Dependencies (1)

- [hoist-non-react-statics](https://npm.io/package/hoist-non-react-statics.md) ^2.5.0

## Alternatives

- [mobx-react](https://npm.io/package/mobx-react.md) — 2.8M weekly downloads
- [rc-tree](https://npm.io/package/rc-tree.md) — 2.6M weekly downloads
- [@react-oauth/google](https://npm.io/package/@react-oauth/google.md) — 1.3M weekly downloads
- [@wagmi/connectors](https://npm.io/package/@wagmi/connectors.md) — 877.0K weekly downloads
- [vee-validate](https://npm.io/package/vee-validate.md) — 836.4K weekly downloads

## Recent versions

- 0.1.5 (latest) — 2018-10-15
- 0.1.4 — 2018-09-05
- 0.1.3 — 2018-08-30
- 0.1.2 — 2018-08-30
- 0.1.1 — 2018-05-24
- 0.1.0 — 2018-05-18

## README

Welcome to React Optimist. A simple API for optimistic UI, using React and taking advantage of the [new Context API](https://reactjs.org/docs/context.html).
Used and maintained by [Swipes](https://swipesapp.com)

# Idea
A user clicks on a button, you want to save the new state to a server, but you don't want to show a loader in the meantime. react-optimist let's you easily queue requests in the background while showing the new value. Also known as optimistic ui.

# Installation [(more options)](https://github.com/swipesapp/react-optimist/blob/master/docs/installation.md)
```
$ npm install --save react-optimist
```

# High level
react-optimist consist of two high level API's:
- OptimistProvider is a react class that needs to be added once, similar to Provider (redux), BrowserRouter (react-router) and so on.
- withOptimist is a higher-order-component (HOC) that you wrap any class that either needs to access to the optimistic data, or will be creating it (or both :). It injects a prop "optimist" into the wrapped component.

```
withOptimist(Component) >> this.props.optimist
```

# The optimist object API
The optimist object injected into your components has a simple api:
Main API:
- [optimist.set(options)](#optimistsetoptions) - queue optimistic requests
- [optimist.get(key, [fallback])](#optimistgetkey-fallback) - get optimistic values
Advanced:
- [optimist.setDefaultOptions(options)](#optimistsetdefaultoptionsoptions) - identify future calls and set default options
- [optimist.identify(id)](#optimistidentifyid) - identify future calls and set default options


## optimist.set(options)
**Params**
- options `object` - An option object

| Option | Type | Default value | Description |
| --- | --- | --- | --- |
| key | string | **(required)** | A key for the queue (ex: goal-reorder, task-119-complete) |
| value | any | **(required)** | The value trying to be sent to the server and that should be used (optimistic) |
| handler | function | **(required)** | The async handler, (next) => {}, you must call next when done |
| serial | bool | false | Run all requests added to this queue, not just the last. |
| clearOnError | boolean | true | When you return an error to next, wipe future requests |
| debounce (coming soon) | number | 0 (ms) | Postpone the server request with x ms from now |
| throttle (coming soon) | number | 0 (ms) | Run server requests every x ms |


## optimist.get(key, [fallback])
Retreive the current optimistic value or an optional fallback value. 

**Params**
- key `string` - entry for the store
- fallback `any value` - value to be used if nothing is in store

**Returns**: `store value or fallback`

## optimist.setDefaultOptions(options)
This will set default options for future calls to set/get.

**Params**
- options `object` - An option object defining defaults, see optimist.set above for supported props.

## optimist.identify(id)
This will prepend id for calls to set/get. **Not required to run this first**

**Params**
- id `string` - An id to prepend future calls to optimist.set (useful for id of a task/project/etc)

# Other projects
Used and maintained by [Swipes](https://swipesapp.com)

- [swiss-react](https://github.com/swipesapp/react-swiss) - A CSS-in-js solution with sass-like features and an epic syntax.

---
_Source: https://npm.io/package/react-optimist · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._