@libre/atom

A way to manage shared, synchronous, independent state

Inspired by atoms in Clojure(Script)

Description

Put your state in an Atom:

import { Atom } from "@libre/atom";

const appState = Atom.of({
  color: "blue",
  userId: 1
});

Read state with deref

You can't inspect Atom state directly, you have to dereference it, like this:

import { deref } from "@libre/atom";

const { color } = deref(appState);

Update state with swap

You can't modify an Atom directly. The main way to update state is with swap. Here's its call signature:

function swap<S>(atom: Atom<S>, updateFn: (state: S) => S): void;

updateFn is applied to atom's state and the return value is set as atom's new state. There are just two simple rules for updateFn:

1. it must return a value of the same type/interface as the previous state
2. it must not mutate the previous state

To illustrate, here is how we might update appState's color:

import { swap } from "@libre/atom";

const setColor = color =>
  swap(appState, state => ({
    ...state,
    color: color
  }));

Take notice that our updateFn is spreading the old state onto a new object before overriding color. This is an easy way to obey the rules of updateFn.

Installation

react-atom has zero dependencies!

npm i -S @libre/atom

Documentation

You can find API docs for @libre/atom here

Contributing / Feedback

Please open an issue if you have any questions, suggestions for improvements/features, or want to submit a PR for a bug-fix (please include tests if applicable).