immutability-helper-helper

This is a wrapper around immutability-helper - a library that helps to produce a mutated copy of data without changing the original source. This wrapper exists because the original syntax is too messy.

Installation:

yarn add immutability-helper-helper
# or
npm install immutability-helper-helper

Usage:

const op = require("immutability-helper-helper");
// OR
import op from "immutability-helper-helper";

// Then
const original = { a: { b: { c: 0 } } };
const copy = op(original).set("a.b.c", 1);

Examples

Examples below show how the same operation would be done using immutability-helper directly, and then using this wrapper.

Simple push

const initialArray = [1, 2, 3];

// Before:
const newArray = update(initialArray, { $push: [4] }); // => [1, 2, 3, 4]

// After:
const newArray = op(initialArray).push(4); // => [1, 2, 3, 4]

Nested collections

const collection = [1, 2, {a: [12, 17, 15]}];

// Before:
const newCollection = update(collection, {2: {a: {$splice: [[1, 1, 13, 14]]}}});
// => [1, 2, {a: [12, 13, 14, 15]}]

// After:
const newCollection = op(collection, '2.a').splice([1, 1, 13, 14]])

Setting via callback

const obj = { a: 5, b: 3 };

// Before:
const newObj = update(obj, { b: { $apply: x => x * 2 } }); // => {a: 5, b: 6}

// After:
const newObj = op(obj, "b").apply(x => x * 2); // => {a: 5, b: 6}

Merge

const obj = { a: 5, b: 3 };

// Before:
const newObj = update(obj, { $merge: { b: 6, c: 7 } }); // => {a: 5, b: 6, c: 7}

// After:
const newObj = op(obj).merge({ b: 6, c: 7 }); // => {a: 5, b: 6, c: 7}

Computed paths

const collection = { children: ["zero", "one", "two"] };
const index = 1;

// Before:
const newCollection = update(collection, {
	children: { [index]: { $set: 1 } }
});
// => {children: ['zero', 1, 'two']}

// After:
const newCollection = op(collection, `children.${index}`).set(1);
// => {children: ['zero', 1, 'two']}

Batch operations

// Before:
const newData = update(myData, {
	x: { y: { z: { $set: 7 } } },
	a: { b: { $push: [9] } }
});

// After:
const newData = op(myData)
	.begin()
	.set("x.y.z", 7)
	.push("a.b", 9)
	.end();

For batch operations, path given to the op will be used as a common path prefix.

const original = {
	a: "b",
	c: {
		d: "e",
		f: [1],
		g: [2],
		h: [3],
		i: { j: "k" },
		l: 4,
		m: "n"
	}
};

// Before:
const altered = update(original, {
	c: {
		d: { $set: "m" },
		f: { $push: [5] },
		g: { $unshift: [6] },
		h: { $splice: [[0, 1, 7]] },
		i: { $merge: { n: "o" } },
		l: { $apply: x => x * 2 },
		m: x => x + x
	}
});

// After:
const altered = op(original, "c")
	.begin()
	.set("d", "m")
	.push("f", 5)
	.unshift("g", 6)
	.splice("h", 0, 1, 7)
	.merge("i", { n: "o" })
	.apply("l", x => x * 2)
	.apply("m", x => x + x)
	.end();