pure-assign

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

npm install --save pure-assign

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:

userObject.firstName = "Anastasia";
userObject.lastName = "Steele";

with calls to Object.assign(), creating a new object with the updated values:

const updatedUserObject = Object.assign({}, userObject, {
  firstName: "Anastasia",
  lastName: "Steele"
});

or alternatively with ES7's spread operator and an appropriate transpiler:

const updatedUserObject = {
  ...userObject,
  firstName: "Anastasia",
  lastName: "Steele",
};

A drawback of this approach is that a new object is created even if the new properties are identical to the old ones. Beyond the minor performance impact, this can have greater consequences if certain updates are triggered by data "changes." For example, React developers may attempt to avoid unnecessary re-renders by using PureComponent, 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 re-renders since the old props do not have object-equality with the new props, despite having the same values.

This is where pureAssign() comes in. pureAssign(object, updates) is equivalent to Object.assign({}, object, updates), but will return the original object if nothing would be changed. For instance:

import pureAssign from "pure-assign";

const userObject = { firstName: "Anastasia", lastName: "Steele" };
const updatedUserObject = pureAssign(userObject, { firstName: "Anastasia" });
console.log(userObject === updatedUserObject); // true

Note that unlike Object.assign(), the first argument of {} is absent.

Like Object.assign(), multiple update arguments may be given, where values found in later objects take precedence over earlier ones. A new object is returned only if the final result of applying all updates has different values from the original object. For example:

import pureAssign from "pure-assign";

const userObject = { firstName: "Anastasia", lastName: "Steele" };

const updatedUserObject1 = pureAssign(
  userObject,
  { firstName: "Christian", lastName: "Kavanagh" },
  { firstName: "Kate" }
);
console.log(updatedUserObject1); // { firstName: "Kate", lastName: "Kavanagh" }

const updatedUserObject2 = pureAssign(
  userObject,
  { firstName: "Ana", lastName: "Steele" },
  { firstName: "Anastasia" }
);
console.log(userObject === updatedObject2); // true

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:

import pureAssign from "pure-assign";

const userObject = { firstName: "Anastasia", lastName: "Steele" };

const updatedUserObject = pureAssign(userObject, { firstNarm: "Ana" });
// Type error because "firstNarm" is not a property of userObject.

Copyright © 2017 David Philipson