instead

instead is a deep-replace function which is value-wise equivalent to the expression a = b but expressed as a = instead( a, b ). However, unike pure assignment, or Object.assign() or any of the deep-assign packages, instead replaces values, object properties and array items with the new value, only if they differ.

If a and b serializes to the exact same, (a = b) === b, but instead(a, b) === a.

This is sometimes extremely handy when referencial equality matters, especially when equality can optimize away unnecessary logic, such as in React.

Example:

const previousValue = {
    foo: { b: 1 },
    bar: { c: 2 },
};
const incomingValue = {
    foo: { b: 1 },
    bar: { c: 3 },
};
const newValue = instead( previousValue, incomingValue );
// Incoming {.foo} is equivalent to previous {.foo}, so reference is kept:
( newValue.foo === previousValue.foo ); // true
( newValue.bar === incomingValue.bar ); // true

Usage

npm i instead, yarn add instead or similar.

instead is default exported and exported as a property instead, so:

import instead from 'instead'
// same as
const { instead } = require( 'instead' );