Path

This module contains simple utilities to work with embedded objects using paths.

path.js

Legend for tables

• API
  • object — an object to work with.
  • path — a path to a nested object. It can be one of the following:
    • string — a path to a nested object separated by delimiter.
    • array — an array of names as strings, symbols, or integers.
  • delimiter — a string that separates names in path. Defaults to '.'.
    • It can be set to any value accepted by String.prototype.split(): a string, a regular expression, or a special object with a [Symbol.split] method.
  • defaultValue — a default value to return if path is not found. Defaults to undefined.
    • It can be set to any value. Usually it represents some default value, but it can represent a special "missing" or "incorrect" value. For example, it can be set to a unique Symbol() so the returned value can be checked in the case of failure.

Objects indexed by path can be any type of non-null objects, including arrays, and functions. Other values do not support indexing.

The following utilities are available:

Function	Return value	Description
get(object, path, {delimiter, defaultValue})	value	Get value from a nested object by path.
set(object, path, value, {delimiter, defaultValue})	value	Set value in a nested object by path.
forceSet(object, path, value, {delimiter})	value	Set value in a nested object by path creating/replacing missing or incorrect objects.
remove(object, path, {delimiter, defaultValue})	value	Remove value from a nested object by path and return the removed value.

In case of failure to reach a value, defaultValue is returned. Otherwise, get() returns the requested value, set() returns the set value, and remove() returns the removed value.

forceSet() is similar to set() but it creates missing or incorrect objects. If the root object is not suitable to create sub-objects, forceSet() throws an error. It will throw in the case of an empty path. It will always return the set value. When replacing objects, forceSet() will overwrite existing properties. It uses {} as missing objects.

Examples

get() and set():

import {get, set} from 'meta-toolkit/path.js';

const object = {a: {b: {c: 1}}};

get(object, 'a.b.c'); // 1
get(object, 'a.b');   // {c: 1}
get(object, 'a.d');   // undefined

get(object, 'a.d', {delimiter: '.', defaultValue: NaN}); // NaN
get(object, 'a/b/c', {delimiter: '/'});                  // 1
get(object, ['a', 'b', 'c']);                            // 1

set(object, 'a.b.c', 2);
set(object, 'a.b.d', 3);

const key = Symbol();
object[key] = {};
set(object, [key, 'x'], 4);

const array = [1, 2, 3];

set(array, '1', {a: 1}); // array = [1, {a: 1}, 3]
get(array, '1.a');       // 1

forceSet() and remove():

import {forceSet, remove} from 'meta-toolkit/path.js';

const object = {};

forceSet(object, 'a.b.c', 1); // object = {a: {b: {c: 1}}}
forceSet(object, 'a.b.d', 2); // object = {a: {b: {c: 1, d: 2}}}
forceSet(object, 'b', 3);     // object = {a: {b: {c: 1, d: 2}}, b: 3}
forceSet(object, 'b.c', 4);   // object = {a: {b: {c: 1, d: 2}}, b: {c: 4}}

remove(object, 'a.b');        // object = {a: {}, b: {c: 4}}
remove(object, 'b.c');        // object = {a: {}, b: {}}
remove(object, 'a');          // object = {b: {}}

Exports

All functions are exported by their names. There is no default export.