State management utilities based on RxJS
This library provides a very thin wrapper around some RxJS objects that are useful for state management.
There are only two main components: atom and combine.
All functions are importable in the usual way:
import { atom } from "@hungry-egg/rx-state";This is very simply a container for any value that chang
8000
es. It's a thin wrapper around an RxJS BehaviorSubject.
Where you'd normally have a static value
const name = "Jerry";you simply wrap with atom
const name$ = atom("Jerry");The $ at the end is a convention sometimes used to indicate an observable object.
Now you can subscribe to updates with a callback
const sub = name$.subscribe((name) => console.log(`Name is now ${name}`));so that when it's changed the callback is called
const name$.set("Tom"); // Logs "Name is now Tom"To avoid memory leaks you should unsubscribe when finished
sub.unsubscribe();The atom function returns a WritableAtom, which has the following methods:
const $name = atom("Jerry");
$name.get() // "Jerry"
$name.set("Tom") // sets value to "Tom" and notifies subscribers
$name.update(n => n + " Mander") // set to "Jerry Mander" -
// use instead of set if you want to use the previous value
const uppercaseName$ = $name.pipe( // pipe can be used as per usual in RxJS,
map(n => n.toUpperCase()), // and returns an RxJS observable
...
)
const lowercaseName$ = $name.map(n => n.toLowerCase()) // "map" is provided for convenience so you
// don't need pipe, and returns a ReadonlyAtom
const $nameRO = $name.readonly() // returns a read-only version of the atom (ReadonlyAtom)
$nameRO.get() // "Jerry Mander"
$nameRO.set(...) // ERROR - METHOD DOESN'T EXIST!
$name.destroy() // rarely used but can use to remove all subscribersThe ReadonlyAtom is similar but only has get, map, pipe and subscribe.
This is a convenience method for creating a read-only atom, that also yields a setter function.
const [count$, setCount] = readonlyAtom(4);
count$.get(); // 4 - this is just a ReadonlyAtom
setCount(7);
count$.get(); // 7This would be useful for e.g. using in a class, where the read-only atom is public, but the setter is private:
class Person {
public name$: ReadonlyAtom<string>;
private setName: (name: string) => void;
constructor(initialName: string) {
[this.name$, this.setName] = readonlyAtom(initialName); // NOTE the parentheses when doing this
}
//... use this.setName("...") internally
}
const person = new Person("Fred");
person.name$.set("Bubba"); // ERROR: name$ is readonly so has no 'set'This combines RxJS observables or atoms in a way that is useful for efficiently using derived values.
If:
- the
atomis analogous to a Redux store (or part of),
then
combineis analogous to memoized selectors like Reselect.
Given multiple atoms (or other synchronous RxJS observables)
const names$ = atom(["Geoffrey", "Bungle", "George", "Zippy"]);
const selectedIndex$ = atom(1);Then you can combine them into a new observable with a tuple
const selectedName$ = combine(
[names$, selectedIndex$], // tuple of multiple observables
([names, index]) => names[index] // calculate new value derived from values from observables
);
selectedName$.get(); // "Bungle"or with an object
const selectedName$ = combine(
{ names: names$, idx: selectedIndex$ }, // object lookup of multiple observables
({ names, idx }) => names[idx] // calculate derived value
);
selectedName$.get(); // "Bungle"The new observable is efficient in that
- it only makes the calculation (the 2nd argument function) once when any of its input observables have changed
- it doesn't make the calculation if no-one is subscribing
In both forms you can also call combine with no 2nd argument
const selectedName$ = combine({ names: names$, idx: selectedIndex$ }); // = an observable that emits {names: string[], idx: number} objects
const selectedName$ = combine([names$, selectedIndex$]); // = an observable that emits [string[], number] objectsThis library provides a convenience method for synchronously getting the value from an RxJS observable
get(count$); // 7This only works in cases where it's able to give its current value synchronously either because
- it calls subscription callbacks synchronously, or
- it's a
BehaviorSubject
Otherwise it will throw an error
const click$ = fromEvent(document, "click");
get(click$); // THROWS AN ERROR -
// it doesn't make sense here as click$ is asynchronousyarn build
yarn watch
yarn test