# live-value

> A simple mechanism for connecting React components to changing model data

Latest version **0.0.7** (published 2022-08-28) · MIT license · 0 weekly downloads

## Install

```sh
npm install live-value
pnpm add live-value
yarn add live-value
bun add live-value
```

## Health

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

Positive: has types; esm support; no vulnerabilities; high quality score.

Warnings: low downloads; pre 1.0.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.0.7 |
| Published | 2022-08-28 |
| First published | 2021-09-20 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 0 |
| Unpacked size | 68.6 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | Nathan Abramson |
| Maintainers | arista2020 |
| Keywords | typescript, react |

## Links

- npm: https://www.npmjs.com/package/live-value
- npm.io page: https://npm.io/package/live-value

## 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.0.7 (latest) — 2022-08-28
- 0.0.6 — 2021-10-05
- 0.0.5 — 2021-10-05
- 0.0.4 — 2021-10-04
- 0.0.3 — 2021-10-04
- 0.0.2 — 2021-10-04
- 0.0.1 — 2021-09-20

## README

# live-value

`live-value` is a simple mechanism for connecting React components to changing data.  The data is contained in `LiveValue` objects, which each expose a single `value` property that an application may change as needed.  For example, this `LiveValue` contains a counter `value` that increments every second:

```
import {LiveValue} from "live-value";

const counter = new LiveValue(0);
setInterval(()=>counter.value++, 1000);
```

A React component may then pass the `LiveValue` object to a `useLiveValue` hook.  The current `value` of the `LiveValue` will be provided to the React component, and if the application later changes that `value` property, the React component will be re-rendered.  For example, this component will display the value of the counter, re-rendering every time the counter's `value` property changes:

```
import {LiveValue, useLiveValue} from "live-value";

function ShowCount(props: {
  counter: LiveValue<number> // (for those using TypeScript)
}) {
  const {counter} = props
  const currentCount = useLiveValue(counter)
  return <div>Current count: {currentCount}</div>;
}
```

When updating the `value` property, the usual React rules apply for registering the update: the actual value of the property must change, and if the value is an Object or Array, a different Object or Array identity must be assigned.

### Additional Notification API's

`LiveValue` provides a simple API that allows applications to be notified when a value may have changed, either because the `value` was set directly, or because a dependency's value changed.  This effectively offers applications the same ability given to the `useLiveValue` hook:

```
addListener(listener: ()=>void, name: string|null = null)
removeListener(listener: ()=>void)
```
The optional `name` passed to addListener is used for debugging, described below.

`LiveValue` can also generate Promises that resolve the next time the `LiveValue`'s value changes, or matches a given test function.  These Promises can optionally be set to reject if a specified timeout elapses before the required condition is met.

```
onChange(timeoutMsec:number|null = null):Promise<T>
onMatch(test: (val:T)=>boolean, timeoutMsec:number|null = null):Promise<T>
```

Sample usage:

```
const newValue = await liveValue.onChange()
const matchingValue = await liveValue.onMatch(newVal=>newVal != null)
```

### Debugging

`live-value` provides insight into its inner workings by emitting events at key points of its operation: when a `LiveValue` is created, when a value is changed, when a computed value is assigned to "listen" to another value, when a `useLiveValue` hook is set to re-render, etc.  The full list of events is found at [DebugEvent](https://github.com/arista/live-value/blob/main/src/DebugEvent.ts).

An application can monitor the events by using listeners:

```
LiveValue.addDebugListener(listener:(e:DebugEvent)=>void):void
LiveValue.removeDebugListener(listener:(e:DebugEvent)=>void):void
LiveValue.debugEventToString(e:DebugEvent):string
```
The last method will convert a `DebugEvent` to a human-readable string.  For convenience, an application can also call:

```
LiveValue.enableDebugToConsole()
LiveValue.disableDebugToConsole()
```
This will automatically convert all `DebugEvents` to human-readable strings and log them through `console.log`.  A React app can do the same thing with a component:

```
<LiveValue.DebugToConsole enable={true|false} />
```

The debugging events and logs include names for the various objects and operations: LiveValue instances, useLiveValue hooks, listeners, onChange/onMatch, etc.  By default, these names are generated automatically using in incrementing counter, but can be overridden:

```
new LiveValue(10, "currentAge")
useLiveValue(lv, "displayCurrentAge")
lv.addListener(l, "myListener")
lv.onChange(5000, "waitingForResult")
lv.onMatch(5000, "waitingForGoodResult")
```

A name can be specified as a string, or as a function that takes the current id counter value and returns the name:

```
new LiveValue(10, id=>`currentAge#${id}`)
```

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