deep-props.set

deep-props.set

Sets values within nested objects; creates structure if not found. Supports setting within Objects, Arrays, Maps, Sets, WeakMaps, and WeakSets; supports creation of Objects, Arrays, and Maps.

Uses the deep-props.get module for dataset exploration. As such, allows for setting within all types supported by the deep-props.get module (with the exception of strings).

In terms of new structure creation, keys are analyzed in the following manner in order to determine what kind of structure to construct:

• Number keys (or string numbers) construct arrays.
• String keys construct Objects.
• Object keys construct Maps.

The next key along the path is used during this structure determination.

Behavior can be customized by using either the forceConstructor or the setCustomizer settings in the module options.

See the usage examples for an overview of different types of data structures.

Getting Started

The following installation, testing, and deployment instructions assume that deep-props.set will be installed as a standalone module. For instructions on how to install and test all deep-props modules, please refer to the main README. Functionality of the module remains the same in both cases.

Prerequisites

Node.JS version 8.7.0 or above.

Installing

npm install deep-props.set

Testing

The following command will test the package for errors. It prints a selection of examples to the console; scroll through its output if you want to learn more about the utility.

npm test --prefix /path/to/node_modules/deep-props.set

Deployment

const set = require('deep-props.set')

Usage

Note: For string paths using standard settings, '.' is considered the same as '[' and ']'. See Options for instructions for customizing this behavior.

Setting within existing Object structure

const nest = { foo: { bar: { baz: 'beh' } } }

// Both return: { foo: { bar: { baz: 'qux' } } }
set(nest, 'foo.bar.baz', 'qux')
nest

Setting within existing Array structure

const nest = [[['foo']]]

// Both return: [[['bar']]]
set(nest, '0.0.0', 'bar')
nest

Setting within existing Map structure

const nest = new Map().set(
  'foo', new Map().set(
    'bar', new Map().set(
      'baz', 'beh'
    )
  )
)

// Both return: Map { 'foo' => Map { 'bar' => Map { 'baz' => 'qux' } } }
set(nest, 'foo.bar.baz', 'qux')
nest

Setting within existing Set structure

const nest = new Set([
  new Set([
    new Set([
      'foo'
    ])
  ])
])

// Both return: Set { Set { Set { 'bar' } } }
set(nest, '0.0.0', 'bar')
nest

// Both return: Set { Set { Set { 'bar', 'baz' } } }
set(nest, '0.0.1', 'baz')
nest

Creation of new Object structure

const nest = {}

// Both return: { foo: { bar: { baz: 'qux' } } }
set(nest, 'foo.bar.baz', 'qux')
nest

Creation of new Array structure

const nest = []

// Both return: [[['foo']]]
set(nest, '0.0.0', 'foo')
nest

Creation of new Map structure

const nest = new Map()

// Both return: Map { ['foo'] => Map { ['bar'] => Map { ['baz'] => 'beh' } } }
set(nest, [['foo'], ['bar'], ['baz']], 'beh')
nest

Documentation

See:

• API Docs
• Global Docs

Module: set

Sets values within nested objects; creates structure if not found. Supports setting within Objects, Arrays, Maps, Sets, WeakMaps, and WeakSets; supports creation of Objects, Arrays, and Maps.

Parameters:

Name	Type	Attributes	Default	Description
host	deep-props.set~Host			Container to search within.
path	deep-props.set~Path			Path to desired property.
data	*			Data to set at endpoint of path.
opt	deep-props.set~Options	<optional>	{}	Execution settings.

Source:

• deep-props.set/index.js, line 365

Returns:

True if successful, false if not. If opt.gen === true, returns a generator that yields each search step.

Type

boolean | deep-props.set~ResultGenerator

Versioning

Versioned using SemVer. For available versions, see the Changelog.

Contribution

Please raise an issue if you find any. Pull requests are welcome!

Author

• Justin Collier - jpcx

License

This project is licensed under the MIT License - see the LICENSE file for details

Changelog

0.1.2 (2018-05-26)

Since: deep-props 0.3.2

| Changes since 0.1.1 | Release Notes | README | | --- | --- | --- |

| Source Code (zip) | Source Code (tar.gz) | | --- | --- |

Features

• docs: Clarified structure creation documentation.

<a name="0.1.1"></a>