path-next

This is a set of functions that take an object and a path to a property in the object and return a new object with a specific kind of change made at that path.

The original object is not modified. Modified parts of the object tree are cloned. Other parts are shared between old and new objects.

While this library is not specific to React, it is particularly useful in React because there are many cases where the functions provided here can simplify the code.

For example, suppose setState is being used to increment the score in a game that is at the state path user.game.score. Without using this library one might write code like the following:

this.setState(state => {
  const {user} = state;
  const {game} = user;
  const {score} = game;
  return {
    ...state,
    user: {
      ...user,
      game: {
        ...game,
        score: score + 1
      }
    }
  };
});

Using this library the code above can be simplified to the following:

this.setState(state =>
  transformPath(state, 'user.game.score', score => score + 1)
);

The functions provided are described below in alphabetical order.

deepFreeze

This freezes a given object and all objects inside it. Attempts to modify any properties in this object, no matter how deeply nested, will result in an error in strict mode or be silently ignored in non-strict mode. This is useful to catch attempts to modify objects that should be immutable.

deepFreeze(person);

deletePath

This deletes the property at a given path within an object.

deletePath(person, 'address.city');

filterPath

This removes elements from an array found at a given path within an object.

// Remove the color green if it exists.
const newPerson = filterPath(
  person,
  'favorites.colors',
  color => color !== 'green'
);

getPath

This retrieves the value of a property at a given path.

const colors = getPath(person, 'favorites.colors');

mapPath

This modifies the values in an array at a given path.

const newPerson = mapPath(person, 'favorite.colors', color =>
  color.toUpperCase()
);

pushPath

This appends values to an array at a given path.

// Add the colors yellow and orange the existing array of colors.
const newPerson = mapPath(person, 'favorite.colors', 'yellow', 'orange');

setPath

This changes the value at a given path.

const newPerson = setPath(person, 'address.city', 'New York');

transformPath

This changes the value at a given path based on its current value.

const newPerson = transformPath(person, 'age', age => age + 1);

Path Concerns

If the layout of objects is expected to change over time and the need to revisit hard-coded paths in these function calls is a concern, consider using constants for the paths so that only those values need to be changed.

For example, create the file path-constants.js containing:

const export GAME_HIGH_SCORE = 'game.statistics.highScore';
const export USER_CITY = 'user.address.city';

Then in files that use these paths, do something like this:

import {GAME_HIGH_SCORE, USER_CITY} from './path-constants';
setPath(user, USER_CITY, 'St. Louis');
transformPath(gameData, GAME_HIGH_SCORE, score => score + 1);

With this approach, if the paths change it is only necessary to update these constants.