unchanged
A tiny (~2.1kB minified+gzipped), fast, unopinionated handler for updating JS objects and arrays immutably.
Supports nested key paths via path arrays or dotty syntax, and all methods are curriable (with placeholder support) for composability. Can be a drop-in replacement for the lodash/fp
methods get
, set
, merge
, and omit
with a 90% smaller footprint.
Table of contents
- unchanged
Usage
; ; // handle standard properties; // or nested properties; // all methods are curriable;;
NOTE: There is no default
export, so if you want to import all methods to a single namespace you should use the import *
syntax:
;
Types
This library is both written in, and provided with, types by TypeScript. The internal types used for specific parameters are scoped to the unchanged
namespace.
// the path used to compute nested locations;// the callback used in transform methods;// the generic object that is computed upon, either an array or object
Notice in the Unchangeable
interface, there is no reference to symbols. That is because to date, TypeScript does not support Symbols as an index type. If you need to use symbols as object keys, the best workaround I've found is to typecast when it complains:
; ;
If there is a better alternative for having dynamic Symbol indices, let me know! Happy to accept any PRs from those more experienced in TypeScript than myself.
Standard methods
get
;
Get the value at the path
requested on the object
passed.
; console.logget"foo[0].bar", object; // bazconsole.logget, object; // baz
getOr
;
Get the value at the path
requested on the object
passed, with a fallback value if that path does not exist.
; console.loggetOr"blah", "foo[0].bar", object; // bazconsole.loggetOr"blah", , object; // bazconsole.loggetOr"blah", "foo[0].nonexistent", object; // blah
set
;
Returns a new object based on the object
passed, with the value
assigned to the final key on the path
specified.
; console.logset"foo[0].bar", "quz", object; // {foo: [{bar: 'quz'}]}console.logset, "quz", object; // {foo: [{bar: 'quz'}]}
remove
;
Returns a new object based on the object
passed, with the final key on the path
removed if it exists.
; console.logremove"foo[0].bar", object; // {foo: [{}]}console.logremove, object; // {foo: [{}]}
has
;
Returns true
if the object has the path provided, false
otherwise.
; console.loghas"foo[0].bar", object; // trueconsole.loghas, object; // trueconsole.loghas"bar", object; // false
is
;
Returns true
if the value at the path
in object
is equal to value
based on SameValueZero equality, false
otherwise.
; console.logis"foo[0].bar", "baz", object; // trueconsole.logis, "baz", object; // trueconsole.logis"foo[0].bar", "quz", object; // false
not
;
Returns false
if the value at the path
in object
is equal to value
based on SameValueZero equality, true
otherwise.
; console.lognot"foo[0].bar", "baz", object; // falseconsole.lognot, "baz", object; // falseconsole.lognot"foo[0].bar", "quz", object; // true
add
;
Returns a new object based on the object
passed, with the value
added at the path
specified. This can have different behavior depending on whether the item is an object or an array; objects will simply add / set the key provided, whereas arrays will add a new value to the end.
; // objectconsole.logadd'foo', 'added value' object; // {foo: [{bar: 'baz'}, 'added value']}console.logadd, 'added value', object; // {foo: [{bar: 'baz'}, 'added value']} // arrayconsole.logadd'foo[0].quz', 'added value' object; // {foo: [{bar: 'baz', quz: 'added value'}]}console.logadd, 'added value', object; // {foo: [{bar: 'baz', quz: 'added value'}]}
Notice that the Object
usage is idential to the set
method, where a key needs to be specified for assignment. In the case of an Array
, however, the value is pushed to the array at that key.
NOTE: If you want to add an item to a top-level array, pass null
as the key:
; console.logaddnull, "bar", object; // ['foo', 'bar']
merge
;
Returns a new object that is a deep merge of value
into object
at the path
specified. If you want to perform a shallow merge, see assign
.
;; console.logmerge"baz", object2, object1;/*{ foo: 'bar', baz: { one: 'new value', deeply: { nested: 'other value', untouched: true, }, two: 'value2', three: 'value3 }}
NOTE: If you want to merge
the entirety of both objects, pass null
as the key:
console.logmergenull, object2, object1;/*{ foo: "bar", baz: { one: "value1", deeply: { nested: "value", untouched: true }, two: "value2" }, one: "new value", deeply: { nested: "other value" }, three: "value3"}*/
assign
;
Returns a new object that is a shallow merge of value
into object
at the path
specified. If you want to perform a deep merge, see merge
.
;; console.logassign"baz", object2, object1;/*{ foo: 'bar', baz: { one: 'new value', deeply: { nested: 'other value', }, two: 'value2', three: 'value3 }}
NOTE: If you want to assign
the entirety of both objects, pass null
as the key:
console.logassignnull, object2, object1;/*{ foo: "bar", baz: { one: "value1", deeply: { nested: "value", untouched: true }, two: "value2" }, one: "new value", deeply: { nested: "other value" }, three: "value3"}*/
call
;
Call the method at the path
requested on the object
passed, and return what it's call returns.
; console.logcall"foo[0].bar", , object; // 3console.logcall, , object; // 3
You can also provide an optional fourth parameter of context
, which will be the this
value in the method call. This will default to the object
itself.
; console.logcall"foo[0].bar", , object; // 3console.logcall"foo[0].bar", , object, ; // 0
NOTE: Because context
is optional, it cannot be independently curried; you must apply it in the call when the object
is passed.
Transform methods
Each standard method has it's own related With
method, which accepts a callback fn
as the first curried parameter. In most cases this callback serves as a transformer for the value retrieved, set, merged, etc.; the exception is removeWith
, where the callback serves as a validator as to whether to remove or not.
The signature of all callbacks is the withHandler
specified in Types
. Because extraParams
are optional parameters, they cannot be independently curried; you must apply them in the call when the object
is passed.
getWith
;
Get the return value of fn
based on the value at the path
requested on the object
passed. fn
is called with the current value at the path
as the first parameter, and any additional parameters passed as extraParams
following that.
;; console.loggetWithfn, "foo[0].bar", object; // 'baz'console.loggetWithfn, "foo[0].bar", object, "baz"; // nullconsole.loggetWithfn, , object; // 'baz'console.loggetWithfn, , object, "baz"; // null
getWithOr
;
Get the return value of fn
based on the value at the path
requested on the object
passed, falling back to fallbackValue
when no match is found at path
. When a match is found, fn
is called with the current value at the path
as the first parameter, and any additional parameters passed as extraParams
following that.
;; console.loggetWithOrfn, "quz", "foo[0].bar", object; // 'baz'console.loggetWithOrfn, "quz", "foo[0].bar", object, "baz"; // nullconsole.loggetWithOrfn, "quz", "foo[0].notFound", object, "baz"; // 'quz'console.loggetWithOrfn, "quz", , object; // 'baz'console.loggetWithOrfn, "quz", , object, "baz"; // nullconsole.loggetWithOrfn, "quz", , object, "baz"; // 'quz'
setWith
;
Returns a new object based on the object
passed, with the return value of fn
assigned to the final key on the path
specified. fn
is called with the current value at the path
as the first parameter, and any additional parameters passed as extraParams
following that.
;; console.logsetWithfn, "foo[0].bar", object; // {foo: [{bar: 'quz'}]}console.logsetWithfn, "foo[0].bar", object, true; // {foo: [{bar: 'baz'}]}console.logsetWithfn, , object; // {foo: [{bar: 'quz'}]}console.logsetWithfn, , object, true; // {foo: [{bar: 'baz'}]}
removeWith
;
Returns a new object based on the object
passed, with the final key on the path
removed if it exists and the return from fn
is truthy.
;; console.logremoveWithfn, "foo[0].bar", object; // {foo: [{}]}console.logremoveWithfn, "foo[0].bar", object, true; // {foo: [{bar: 'baz'}]}console.logremoveWith, object; // {foo: [{}]}console.logremoveWith, object, true; // {foo: [{bar: 'baz'}]}
hasWith
;
Returns true
if the return value of fn
based on the value returned from path
in the object
returns truthy, false
otherwise.
;; console.loghasWithfn, "foo[0].bar", object; // trueconsole.loghasWithfn, "foo[0].bar", object, true; // falseconsole.loghasWithfn, , object; // trueconsole.loghasWithfn, , object, true; // falseconsole.loghasWithfn, "bar", object; // false
isWith
;
Returns true
if the return value of fn
based on the value returned from path
in the object
is equal to value
based on SameValueZero equality, false
otherwise.
;; console.logisWithfn, "foo[0].bar", object; // trueconsole.logisWithfn, , object; // trueconsole.logisWithfn, "foo[0].quz", object; // false
notWith
;
Returns false
if the return value of fn
based on the value returned from path
in the object
is equal to value
based on SameValueZero equality, true
otherwise.
;; console.lognotWithfn, "foo[0].bar", object; // falseconsole.lognotWithfn, , object; // falseconsole.lognotWithfn, "foo[0].quz", object; // true
addWith
;
Returns a new object based on the object
passed, with the return value of fn
added at the path
specified. This can have different behavior depending on whether the item is an object or an array; objects will simply add / set the key provided, whereas arrays will add a new value to the end.
; ? value .split"" .reverse .join"" : "new value"; // objectconsole.logaddWithfn, "foo", object; // {foo: [{bar: 'baz'}, 'new value']}console.logaddWithfn, , object; // {foo: [{bar: 'baz'}, 'new value']} // arrayconsole.logaddWithfn, "foo[0].bar", object; // {foo: [{bar: 'zab'}]}console.logaddWithfn, , object; // {foo: [{bar: 'zab''}]}
mergeWith
;
Returns a new object that is a deep merge of the return value of fn
into object
at the path
specified if a valid mergeable object, else returns the original object. If you want to perform a shallow merge, see assignWith
.
;;; console.logmergeWithfn, "baz", object1;/*{ foo: 'bar', baz: { one: 'new value', deeply: { nested: 'other value', untouched: true, }, two: 'value2', three: 'value3 }}*/console.logmergeWithfn, "baz.deeply", object1;/*// untouched object1{ foo: "bar", baz: { one: "value1", deeply: { nested: 'value', untouched: true, }, two: "value2" }}*/
NOTE: If you want to merge
the entirety of both objects, pass null
as the key:
console.logmergeWithfn, null, object1;/*{ foo: "bar", baz: { one: "value1", deeply: { nested: "value", untouched: true }, two: "value2" }, one: "new value", deeply: { nested: "other value" }, three: "value3"}*/
assignWith
;
Returns a new object that is a shallow merge of the return value of fn
into object
at the path
specified if a valid mergeable object, else returns the original object. If you want to perform a deep merge, see mergeWith
.
;;; console.logassignWithfn, "baz", object1;/*{ foo: 'bar', baz: { one: 'new value', deeply: { nested: 'other value', }, two: 'value2', three: 'value3 }}*/console.logassignWithfn, "baz.deeply", object1;/*// untouched object1{ foo: "bar", baz: { one: "value1", deeply: { nested: 'value', untouched: true, }, two: "value2" }}*/
callWith
;
Call the method returned from fn
based on the path
specified on the object
, and if a function return what it's call returns.
; ? fn :console.error"Error: Requested call of a method that does not exist."; console.logcallWithfn, "foo[0].bar", , object; // 3console.logcallWithfn, , , object; // 3callWithfn, "foo[1].nope", object; // Error: Requested call of a method that does not exist.
You can also provide an optional fourth parameter of context
, which will be the this
value in the method call. This will default to the object
itself.
; ? fn :console.error"Error: Requested call of a method that does not exist."; console.logcallWithfn, "foo[0].bar", , object; // 3console.logcallWithfn, "foo[0].bar", , object, ; // 0
NOTE: Because context
is optional, it cannot be independently curried; you must apply it in the call when the object
is passed.
Additional objects
__
A placeholder value used to identify "gaps" in a curried function, allowing for earlier application of arguments later in the argument order.
; ; ; setFooOnThing'bar';
Differences from other libraries
lodash
lodash/fp
(the functional programming implementation of lodash
) is identical in implementation to unchanged
's methods, just with a 10.5x larger footprint. These methods should map directly:
- lodash/fp => unchanged
curry.placeholder
=>__
get
=>get
getOr
=>getOr
merge
=>merge
omit
=>remove
set
=>set
ramda
ramda
is similar in its implementation, however the first big difference is that dot-bracket syntax is not supported by ramda
, only path arrays. The related methods are:
- ramda => unchanged
__
=>__
path
=>get
pathOr
=>getOr
merge
=>merge
omit
=>remove
assocPath
=>set
Another difference is that the ramda
methods that clone (assocPath
, for example) only work with objects; arrays are implicitly converted into objects, which can make updating collections challenging.
The last main difference is the way that objects are copied, example:
Foo.prototype.getValue = ; ; // in ramda, both own properties and prototypical methods are copied to the new object as own properties; console.logramdaResult; // {value: 'foo', bar: 'baz', getValue: function getValue() { return this.value; }}console.logramdaResult instanceof Foo; // false // in unchanged, the prototype of the original object is maintained, and only own properties are copied as own properties; console.logunchangedResult; // {value: 'foo', bar: 'baz'}console.logunchangedResult instanceof Foo; // true
This can make ramda
more performant in certain scenarios, but at the cost of having potentially unexpected behavior.
Other immutability libraries
This includes popular solutions like Immutable.js, seamless-immutable, mori, etc. These solutions all work well, but with one caveat: you need to buy completely into their system. Each of these libraries redefines how the objects are stored internally, and require that you learn a new, highly specific API to use these custom objects. unchanged
is unopinionated, accepting standard JS objects and returning standard JS objects, no transformation or learning curve required.
Browser support
- Chrome (all versions)
- Firefox (all versions)
- Edge (all versions)
- Opera 15+
- IE 9+
- Safari 6+
- iOS 8+
- Android 4+
Development
Standard stuff, clone the repo and npm install
dependencies. The npm scripts available:
benchmark
=> run benchmark suite comparing top-level and deeply-nestedget
andset
operations withlodash
andramda
build
=> runrollup
to builddist
files for CommonJS, ESM, and UMD consumersclean
=> runrimraf
on thedist
folderdev
=> run webpack dev server to run example app / playgrounddist
=> runsclean
andbuild
lint
=> run ESLint against all files in thesrc
folderlint:fix
=> runlint
with autofixing appliedprepublish
=> runsprepublish:compile
when publishingprepublish:compile
=> runlint
,test:coverage
,dist
test
=> run AVA test functions withNODE_ENV=test
test:coverage
=> runtest
but withnyc
for coverage checkertest:watch
=> runtest
, but with persistent watcher