re-mutable
Re-mutable is a lightweight immutability library. There are already some excellent immutability libraries out there like immutable.js and immutability-helpers, so why reinvent the wheel? There are situations where neither are ideal:
#a) Immutable.js
- Regular javascript types must be converted to and from their immutable.js equivalents. This can be awkward if many parts of your code fetche regular objects and introduce them into the store.
- You must use the equivalent apis for the immutable.js objects which take some getting used to.
- Rarely does a slice of state from the store cleanly map to the props of every component. More often you will extract some subset of a slice of state which requires more verbose syntax (eg. <Comp prop1={obj.get("key1")} prop2={obj.get("key2")} />)
#b) Immutability-helpers/React.update
- This is essentially the deprecated React.update function. While very powerful, describing your updates requires creating a nested structure of objects which can be a lot of overhead. In our experience, updates to the store are usually isolated and simple and seldom require the power of React.update. Most often, an action will require you to go to a specific path in the store and update a value.
#Overview
For a more detailed explation, please see the wiki
Like other mutability libraries out there, Re-mutable is optimized through structural sharing; only parts of the store which are modified are cloned. Re-mutable optially also supports operation chaining to prevent unnecessary cloning between calls. Take the following example:
const update = require("re-mutable");
let state = {};
update.set(state, ["a"], 1);
update.set(state, ["b"], 2);
update(state).set(["a"], 1).set(["b"], 2).end();
#Supported functions
Re-mutable supports most common operations on your state:
- set/unset: Can be performed at any path in the state
const update = require("re-mutable");
const state = { x: "remove me", myarray: [0, 1, 2] };
const next = update(state)
.set(["a"], 1)
.unset(["x"])
.unset(["myarray", 1]).end();
console.log(next);
- sort/prepend/concat/splice/push: Can be performend on any item in the store which is an array
const update = require("re-mutable");
const state = { myarray: [0, 1, 2] };
const next = update(state)
.push(["myarray"], 2)
.concat(["myarray"], [3, 4, 5])
.prepend(["myarray"], [-2, -1])
.sort(function (a, b) { return a > b ? -1 : 1; })
.end();
console.log(next);
- increment/decrement: Can be performed on any numeric item in the store
const update = require("re-mutable");
const state = { counts: { i: 5, j: 100 } };
const next = update(state)
.increment(["counts", "i"])
.decrement(["counts", "j"], 10)
.end();
console.log(next)
- toggle: Can flip between true and false at the specified path
const update = require("re-mutable");
const state = { counts: { i: 5, j: false } };
const next = update(state)
.toggle(["counts", "i"])
.toggle(["counts", "j"])
.end();
console.log(next) //{ counts: { i: false, j: true } }
- merge: Merge 2 objects together
const update = require("re-mutable");
const state = { employees: [{ name: "okhtay", id: 5 }] };
const next = update.merge(state, ["employees", { id: 5 }], { lastname: "jones" });
console.log(next); // { employees: [{ name: "okhtay", lastname: "jones", id: 5 }] };
Advanced uses:
- Find state by predicate:
const update = require("re-mutable");
const state = { employees: [{ id: 1, name: "John", salary: 1 }, { id: 2, name: "Jane", salary: 5 } };
const next = update.set(["employees", { name: "Jane" }, "salary"], 3);