dot-prop-immutable

Immutable version of dot-prop with some extensions.

npm install dot-prop-immutable

The motivation for this module is to have a simple utility for changing state in a React-Redux application without mutating the existing state of plain JavaScript objects. If you are going for real immutable data collections take a look at the cool library Immutable.js. A good practice is not to mix the immutable data collections with mutable objects because it can lead to confusion. Immutable objects are not accessed by the default semantics, but implemented by setters and getters.

This library implements 3 helper functions:

get(object, path) --> value
set(object, path, value) --> object
delete(object, path) --> object

None of the functions mutate the input object. For efficiency, the returned object is not a deep clone of the original, but a shallow copy of the objects in the mutated path.

Usage

1var dotProp = require("dot-prop-immutable")
2var state = { todos: [] },
3  index = 0
4
5// Add todo:
6state = dotProp.set(state, "todos", list => [
7  ...list,
8  { text: "cleanup", complete: false },
9])
10// or with destructuring assignment
11state = {
12  ...state,
13  todos: [
14    ...state.todos,
15    { text: "cleanup", complete: false },
16  ],
17}
18//=>  { todos: [{text: 'cleanup', complete: false}] }
19
20// Complete todo:
21state = dotProp.set(state, `todos.${index}.complete`, true)
22// or with destructuring assignment
23state = {
24  ...state,
25  todos: [
26    ...state.todos.slice(0, index),
27    { ...state.todos[index], complete: true },
28    ...state.todos.slice(index + 1),
29  ],
30}
31//=>  { todos: [{text: 'cleanup', complete: true}] }
32
33// Delete todo:
34state = dotProp.delete(state, `todos.${index}`)
35// or with destructuring assignment
36state = {
37  ...state,
38  todos: [
39    ...state.todos.slice(0, index),
40    ...state.todos.slice(index + 1),
41  ],
42}
43//=>  { todos: [] }

get

Access a nested property by a dot path

1// Getter
2dotProp.get({ foo: { bar: "unicorn" } }, "foo.bar")
3//=> 'unicorn'
4
5dotProp.get({ foo: { bar: "a" } }, "foo.notDefined.deep")
6//=> undefined
7
8dotProp.get(
9  { foo: { bar: "a" } },
10  "foo.notDefined.deep",
11  "default value"
12)
13//=> default value
14
15dotProp.get(
16  { foo: { "dot.dot": "unicorn" } },
17  "foo.dot\\.dot"
18)
19//=> 'unicorn'

or use a property array as a path.

1// Use an array as get path
2dotProp.get({ foo: { "dot.dot": "unicorn" } }, [
3  "foo",
4  "dot.dot",
5])
6//=> 'unicorn'

It is also possible to index into an array where the special index $end refers to the last element of the array.

1var obj = {
2  foo: [
3    { bar: "gold-unicorn" },
4    "white-unicorn",
5    "silver-unicorn",
6  ],
7}
8
9// Index into array
10dotProp.get(obj, "foo.1")
11//=> 'white-unicorn'
12
13dotProp.get(obj, "foo.0.bar")
14//=> 'gold-unicorn'
15
16// Index into array with $end
17dotProp.get(obj, "foo.$end")
18//=> 'silver-unicorn'
19
20// If obj is an array
21dotProp.get(
22  [
23    { bar: "gold-unicorn" },
24    "white-unicorn",
25    "silver-unicorn",
26  ],
27  "0.bar"
28)
29//=> 'gold-unicorn'

set

Modify a nested property by a dot path

1// Setter
2var obj = { foo: { bar: "a" } }
3
4var obj1 = dotProp.set(obj, "foo.bar", "b")
5//obj1 => {foo: {bar: 'b'}}
6
7var obj2 = dotProp.set(obj1, "foo.baz", "x")
8//obj2 => {foo: {bar: 'b', baz: 'x'}}

where obj, obj1, obj2, obj3 all are different objects.

Use a function to modify the selected property, where first argument is the old value.

1// Setter where value is a function (get and set current value)
2dotProp.set({ foo: { bar: "a" } }, "foo.bar", v => v + "bc")
3//=> {foo: {bar: 'abc'}}

Modify a nested array

1var obj = {
2  foo: [
3    { bar: "gold-unicorn" },
4    "white-unicorn",
5    "silver-unicorn",
6  ],
7}
8
9// Index into array
10dotProp.set(obj, "foo.1", "platin-unicorn")
11//=> {foo: [{bar: 'gold-unicorn'}, 'platin-unicorn', 'silver-unicorn']}
12
13dotProp.set(obj, "foo.0.bar", "platin-unicorn")
14//=> {foo: [{bar: 'platin-unicorn'}, 'white-unicorn', 'silver-unicorn']}
15
16// Index into array with $end
17dotProp.set(obj, "foo.$end", "platin-unicorn")
18//=> {foo: [{ bar: 'gold-unicorn'}, 'white-unicorn', 'platin-unicorn']}

delete

Delete a nested property/array by a dot path

1var obj = {
2  foo: [
3    { bar: "gold-unicorn" },
4    "white-unicorn",
5    "silver-unicorn",
6  ],
7}
8
9// delete
10dotProp.delete(obj, "foo.$end")
11//=> {foo: [{ bar: 'gold-unicorn'}, 'white-unicorn']}
12
13dotProp.delete(obj, "foo.0.bar")
14//=> {foo: [{}, 'white-unicorn', 'silver-unicorn']}

toggle

Toggle a boolean a value by a dot path.

1var obj = { foo: { bar: true } }
2
3// toggle
4dotProp.toggle(obj, "foo.bar")
5//=> {foo: { bar: false } }

merge

Merge a value by a dot path.

The target value must be an object, array, null, or undefined.

• If target is an object, Object.assign({}, target, param) is used.
• If target an array, target.concat(param) is used.
• If target is null or undefined, the value is simply set.

1var obj = {foo: { bar: {a:1, b:2 } };
2
3// merge object
4dotProp.merge(obj, 'foo.bar', {c:3} );
5//=> {foo: { bar:{ a:1, b:2, c:3} } }
6
7var arr = {foo: { bar: [1, 2] } };
8
9// merge array
10dotProp.merge(arr, 'foo.bar', [3, 4] );
11//=> {foo: { bar:[1, 2, 3, 4 ] }

License

MIT