README.md

Immutable Cursor

Immutable cursors incorporating the Immutable.js API interface over a Clojure-inspired atom

Rationale

In Immutable.js' cursor implementation, all applicable parts of it's native interface are exposed as first-class citizens directly on the cursor, allowing for a rich mutative API.

Each cursor however, holds it's own reference to the root state, which quickly leads to issues with the integrity of the root state when updates are made from derived cursors - i.e not included in a chained sequence with the root cursor.

Solution

A Clojure-inspired atom is placed above the cursor composition, and is the only point of mutation in the entire system. Each cursor references this atom, which ensures that an accurate state representation always flows down the system.

const data = Immutable.fromJS({a: 1, b: 2});

const cursor = Cursor.from(data, (nextValue, prevValue, keyPath) => {
  console.log('Value changed from', prevValue, 'to', nextValue, 'at', keyPath);
});

// Multiple update transactions are serialised.
cursor.set('a', 2);
// Value changed from Map { a: 1, b: 2 } to Map { a: 2, b: 2 } at [ 'a' ]
cursor.set('b', 3);
// Value changed from Map { a: 2, b: 2 } to Map { a: 2, b: 3 } at [ 'b' ]

// Whilst the cursor the itself stays immutable.
cursor.deref(); // => Map { "a": 1, "b": 2 }

This has far reaching consequences when used in component-centric view layers such as React. A typical use case would be to make several derivations of a cursor within a React component before propagating them down the sub-tree as props.

Contributing

1. Fork the repo and create your branch from master
2. npm install
3. Add tests
4. Commit the aforementioned and associated source files. NOTE There is no need to manually create the generated dist files; this, a test run and a linting pass is done automatically every time you make a commit.