# stateful-value

> Values with built-in states. Suitable for async operations.

Latest version **1.0.0** (published 2021-05-19) · SEE LICENSE IN LICENSE license · 0 weekly downloads

## Install

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

## Health

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

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.0.0 |
| Published | 2021-05-19 |
| First published | 2021-05-19 |
| Weekly downloads | 0 |
| License | SEE LICENSE IN LICENSE |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 0 |
| Unpacked size | 26.9 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 0 |
| Maintainers | cnshenj |
| Keywords | stateful, async |

## Links

- npm: https://www.npmjs.com/package/stateful-value
- Repository: https://github.com/cnshenj/stateful-value
- Homepage: https://github.com/cnshenj/stateful-value#readme
- Issues: https://github.com/cnshenj/stateful-value/issues
- npm.io page: https://npm.io/package/stateful-value

## Alternatives

- [@commercetools/sync-actions](https://npm.io/package/@commercetools/sync-actions.md) — 25.1K weekly downloads
- [cwait](https://npm.io/package/cwait.md) — 21.4K weekly downloads
- [@ledgerhq/hw-app-cosmos](https://npm.io/package/@ledgerhq/hw-app-cosmos.md) — 4.2K weekly downloads
- [@financial-times/o-loading](https://npm.io/package/@financial-times/o-loading.md) — 2.8K weekly downloads
- [fa](https://npm.io/package/fa.md) — 185 weekly downloads

## Recent versions

- 1.0.0 (latest) — 2021-05-19

## README

stateful-value: Values with built-in states
===========================================
Please see [ARTICLE.md](https://github.com/cnshenj/stateful-value/blob/main/ARTICLE.md) for the rationale of the package.

# Installation
npm i -S stateful-value

# Usage
To represent a value that could be:
- Unfulfilled: it has not been loaded/populated (e.g. AJAX, user input)
- Error: error encountered during loading operation
- Valid: it has been successfully loaded

```typescript
import { StatefulValue } from "stateful-value";

let data: StatefulValue<string>;
if (isValid(data)) {
    // data is guaranteed to be a string
    console.log(data.length);
}

data = await loadData();
if (isError(data)) {
    // data is guaranteed to be an Error (or subclass of Error) object
    console.error(data.message);
}
```

# API
### Type `StatefulValue<T>`
Defines a type that can represent a value that is either unfulfilled, or is an error, or is valid.

### Function `isUnfulfilled(): boolean`
Determines whether the value is `undefined` or an `Unfulfilled` object.

### Function `isError(): boolean`
Determines whether the value is an `Error` object.

### Function `isValid(): boolean`
Determines whether the value is valid (i.e. an instance of type `T`).

### Function `isNonNull(): boolean`
Determines whether the value is valid and is not `null`.
Note: `null` is considered a valid value if `T` contains it, e.g. `StatefulValue<string | null>`.

### Function `getValue(): T | undefined`
Returns the value if it is valid; otherwise, returns `undefined`.

### Function `getError(): T | undefined`
Returns the value if it is an `Error` object; otherwise, returns `undefined`.

### Function `resolveValue`
```typescript
async function resolveValue<T>(
    callback: () => Promise<T>,
    dependencies: StatefulValue<unknown>[] = []
): Promise<StatefulValue<T>>
```
Resolves a stateful value when all dependencies are valid.
- If any of the dependencies is an error, then return the first dependency error.
- If all dependencies are valid, then invoke the callback to get the target stateful value.
- Otherwise, returns `Unfulfilled`.

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