# retil-source

> Utilities to create and combine suspendable, reactive sources

Latest version **0.28.4** (published 2022-05-17) · MIT license · 0 weekly downloads

## Install

```sh
npm install retil-source
pnpm add retil-source
yarn add retil-source
bun add retil-source
```

## 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.28.4 |
| Published | 2022-05-17 |
| First published | 2020-08-14 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 2 |
| Unpacked size | 177 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | James K Nelson |
| Maintainers | jamesknelson |

## Links

- npm: https://www.npmjs.com/package/retil-source
- npm.io page: https://npm.io/package/retil-source

## Dependencies (2)

- [tslib](https://npm.io/package/tslib.md) ^2.2.0
- [retil-support](https://npm.io/package/retil-support.md) ^0.28.4

## Recent versions

- 0.28.4 (latest) — 2022-05-17
- 0.28.3 — 2022-05-17
- 0.28.2 — 2022-02-14
- 0.28.1 — 2022-02-14
- 0.28.0 — 2022-02-06
- 0.27.0 — 2022-02-04
- 0.26.2 — 2022-01-28
- 0.26.0 — 2021-12-18
- 0.25.0 — 2021-11-11
- 0.24.3 — 2021-10-26
- 0.24.2 — 2021-10-26
- 0.24.1 — 2021-10-26
- 0.24.0 — 2021-10-26
- 0.23.8 — 2021-10-26
- 0.23.4 — 2021-10-17
- … 34 more at https://npm.io/package/retil-source/versions

## README

<h1 align="center">
  retil-source
</h1>

<h4 align="center">
  Superpowers for React state management
</h4>

<p align="center">
  <a href="https://www.npmjs.com/package/retil-source"><img alt="NPM" src="https://img.shields.io/npm/v/retil-source.svg"></a>
</p>

Create and combine asynchronous data sources that work great with React Concurrent Mode.

## Installation

```bash
# For npm users...
npm install --save retil-source

# For yarn users...
yarn add retil-source
```

## Sources don't always have values

Why should a data source return a value before it has one?

```tsx
import { createState, hasSnapshot } from 'retil'

const [stateSource, setState] = createState()
const [getState, subscribe] = stateSource

getState() // throws a promise that resolves to the first value.

setState('yo!')

getState() // now it returns 'yo!'
```

## Examples

Say you have a source that switches between having a value, and *not* having a value -- e.g. because it maps an id to data on a remote server. But you still want to display the latest value.

```ts
import { Source, fuse } from 'retil'

export const fallbackToMostRecent = <T>(source: Source<T>): Source<T> => {
  let fallback: [T] | [] = []
  return fuse(use => {
    const value = use(source, ...fallback)
    fallback = [value]
    return value
  })
}
```

Maybe as well as remembering the most recent value, you'd also like to set a flag indicating whether the source is missing a current value. To do this, you can `use` your source *twice*, with different fallback values. Don't worry, `fuse` will only subscribe to the source once!

```ts
const missingFlag = Symbol('missing')

export function addBusyFlag<T, U>(
  source: Source<T>,
  build: (snapshot: T, flag: boolean) => U,
): Source<U> {
  let fallback: [T] | [] = []
  return fuse((use) => {
    const value = use(source, ...fallback)
    const valueOrFlag = use(source, missingFlag)
    fallback = [value]
    return build(value, valueOrFlag === missingFlag)
  })
}
```

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