pure-assign
v1.0.2
Published
Drop-in replacement for Object.assign() for "updating" immutable objects.
Downloads
880
Maintainers
Readme
Pure Assign
Drop-in replacement for
Object.assign()
for "updating" immutable objects. Unlike Object.assign()
, pureAssign()
will
not create a new object if no properties change.
Installation
With Yarn:
yarn add pure-assign
With NPM:
npm install pure-assign
Usage
pureAssign()
takes one or more arguments. The first argument is a base object,
and the remaining arguments are any number of objects whose properties should be
merged with those of the base object to produce a new object. Unlike
Object.assign()
,
the first argument is not modified. For example:
import pureAssign from "pure-assign";
const user = { firstName: "Anastasia", lastName: "Steele" };
const updatedUser = pureAssign(user, { firstName: "Ana" });
console.log(user); // -> { firstName: "Anastasia", lastName: "Steele" }
console.log(updatedUser); // -> { firstName: "Ana", lastName: "Steele" }
If the resulting object would differ from the original, then a new object is created and returned. Otherwise, the original instance is returned. For example:
const user = { firstName: "Anastasia", lastName: "Steele" };
const updatedUser = pureAssign(user, { firstName: "Anastasia" });
console.log(user === updatedUser); // -> true
In other words, the following are equivalent:
pureAssign(object, ...updates);
Object.assign({}, object, ...updates);
except that when using pureAssign
the original instance is returned if no
changes would be applied.
For TypeScript users, pureAssign
has an additional advantage in that it
catches type errors of the following form, which would be uncaught if using
Object.assign()
or object spread:
const user = { firstName: "Anastasia", lastName: "Steele" };
const updatedUser = pureAssign(userObject, { firstNarm: "Ana" });
// Type error because "firstNarm" is not a property of userObject.
Motivation
Many JavaScript programs treat objects as immutable data. For instance, this is recommended by React and required by Redux. Such programs typically replace object mutation:
const user = { firstName: "Anastasia", lastName: "Steele" };
user.firstName = "Ana";
with calls to Object.assign()
, creating a new object with the updated values:
const updatedUser = Object.assign({}, user, {
firstName: "Ana",
});
or alternatively with ES7's spread operator and an appropriate transpiler:
const updatedUser = { ...user, firstName: "Ana" };
A drawback of this approach is that a new object is created even if the new
properties are identical to the old ones. This may have performance implications
if certain updates are triggered by data "changes." For example, React
developers may attempt to avoid unnecessary re-renders by using
PureComponent
or
React.memo()
, which only
performs an update if its props have "changed" according to a shallow-equality
check. This means that if your updates create new objects with the same values,
they will trigger unnecessary rerenders since the old props do not have
object-equality with the new props, despite being functionally identical.
This is where pureAssign()
comes in. By returning the same instance in cases
where the values haven't changed, pureAssign
avoids triggering unnecessary
updates which use object-equality to determine whether the state has changed.
Copyright © 2017 David Philipson