libre-org/atom

Clojure(Script)-style Atoms for JavaScript & TypeScript

A way to manage shared, synchronous, independent state

Inspired by atoms in Clojure(Script)

 

Description

@libre/atom provides a data type called Atoms and a few functions for working with Atoms. It is heavily inspired by atoms in Clojure(Script). While the full power of Clojure atoms cannot be experienced in JavaScript's single-threaded runtime, Atoms do still offer similar benefits due to the highly asynchronous and event-driven nature of JavaScript.

Atoms provide a predictable way to manage state shared by multiple components of a program as that state changes over time. They are particularly useful in the functional and reactive programming paradigms, where most components of a program are pure functions operating on immutable data. Atoms provide a controlled mechanism for mutability that lets multiple components access and update the same value without risking mutating another component's reference to it in the middle of some process or asynchronous operation.

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: DeepImmutable<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
  }));

Note: 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. If manually spreading values seems tedious, there are many libraries that offer convenient functions for operating on JS data structures in an immutable manner, e.g. see ramda, sanctuary, crocks, or (for the wizards among us) fp-ts.

Installation

NPM: npm install --save @libre/atom

Yarn: yarn add @libre/atom

CDN: <script src="https://unpkg.com/@libre/atom" />

• Exposed on the global object, like so: window["@libre/atom"]

Usage

ES6 import

import { Atom, deref, set, swap } from "@libre/atom";

CommonJS require

const { Atom, deref, set, swap } = require("@libre/atom");

Web <script /> tag

const { Atom, deref, set, swap } = window["@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).