set-value

Set nested properties on an object using dot notation.

Please consider following this project's author, Jon Schlinkert, and consider starring the project to show your :heart: and support.

Install

Install with npm (requires Node.js >=11.0):

$ npm install --save set-value

Heads up!

Please update to version 3.0.1 or later, a critical bug was fixed in that version.

Usage

const set = require('set-value');

const obj = {};
set(obj, 'a.b.c', 'd');

console.log(obj);
//=> { a: { b: { c: 'd' } } }

Params

Signature:

set(object, property_path, value[, options]);

• object {Object}: The object to set value on
• path {String|Symbol|Array}: The path of the property to set.
• value {any}: The value to set on obj[prop]
• options {Object}: See all available options

Object paths

You may pass a string, symbol, or array of strings or symbols. By default, when a string is passed this library will split the string on . or a custom separator It's useful to pass an array

Escaping

Escaping with backslashes

Prevent set-value from splitting on a dot by prefixing it with backslashes:

console.log(set({}, 'a\\.b.c', 'd'));
//=> { 'a.b': { c: 'd' } }

console.log(set({}, 'a\\.b\\.c', 'd'));
//=> { 'a.b.c': 'd' }

Options

options.preservePaths

Do not split properties that include a /. By default, set-value assumes that properties with a / are not intended to be split. This option allows you to disable default behavior.

Note that this option cannot be used if options.separator is set to /.

Type: boolean

Default: true

Example

console.log(set({}, 'https://github.com', true));
//=> { 'https://github.com': true }

console.log(set({}, 'https://github.com', true, { preservePaths: false }));
//=> { 'https://github': { com: true } }

options.separator

Custom separator to use for splitting object paths.

Type: string

Default: .

Example

console.log(set(obj, 'auth/userpass/users/bob', '*****', { separator: '/' }));
//=> { auth: { userpass: { users: { bob: '*****' } } } }

options.split

Custom .split() function to use.

options.merge

Allows you to update plain object values, instead of overwriting them.

Type: boolean|function - A custom merge function may be defined if you need to deep merge. Otherwise, when merge is true, a shallow merge will be performed by Object.assign().

Default: undefined

Example

const obj = { foo: { bar: { baz: 'qux' } } };
set(obj, 'foo.bar.fez', 'zzz', { merge: true });
//=> { foo: { bar: { baz: 'qux', fez: 'zzz' } } }

Benchmarks

Benchmarks were run on a MacBook Pro 2.5 GHz Intel Core i7, 16 GB 1600 MHz DDR3.

# deep (194 bytes)
  deep-object x 823,287 ops/sec ±1.00% (90 runs sampled)
  deep-property x 1,787,990 ops/sec ±0.82% (92 runs sampled)
  deephas x 840,700 ops/sec ±0.95% (93 runs sampled)
  dot-prop x 1,249,663 ops/sec ±0.89% (90 runs sampled)
  dot2val x 2,067,212 ops/sec ±1.08% (91 runs sampled)
  es5-dot-prop x 1,668,806 ops/sec ±0.92% (92 runs sampled)
  lodash-set x 1,286,725 ops/sec ±0.82% (90 runs sampled)
  object-path-set x 1,261,242 ops/sec ±1.63% (90 runs sampled)
  object-set x 285,369 ops/sec ±0.91% (90 runs sampled)
  set-value x 2,076,931 ops/sec ±0.86% (93 runs sampled)

  fastest is set-value, dot2val (by 203% avg)

# medium (98 bytes)
  deep-object x 5,811,161 ops/sec ±1.12% (90 runs sampled)
  deep-property x 4,075,885 ops/sec ±0.91% (90 runs sampled)
  deephas x 1,508,136 ops/sec ±0.82% (92 runs sampled)
  dot-prop x 2,809,838 ops/sec ±1.16% (87 runs sampled)
  dot2val x 4,600,890 ops/sec ±0.76% (91 runs sampled)
  es5-dot-prop x 3,263,790 ops/sec ±0.97% (91 runs sampled)
  lodash-set x 3,486,628 ops/sec ±1.20% (90 runs sampled)
  object-path-set x 3,729,018 ops/sec ±0.90% (92 runs sampled)
  object-set x 973,961 ops/sec ±0.80% (92 runs sampled)
  set-value x 6,941,474 ops/sec ±1.24% (90 runs sampled)

  fastest is set-value (by 206% avg)

# shallow (101 bytes)
  deep-object x 9,416,410 ops/sec ±1.19% (89 runs sampled)
  deep-property x 5,108,536 ops/sec ±0.98% (93 runs sampled)
  deephas x 1,706,979 ops/sec ±0.98% (86 runs sampled)
  dot-prop x 4,045,902 ops/sec ±1.10% (92 runs sampled)
  dot2val x 5,862,418 ops/sec ±0.88% (91 runs sampled)
  es5-dot-prop x 4,439,646 ops/sec ±1.18% (90 runs sampled)
  lodash-set x 9,303,292 ops/sec ±1.19% (89 runs sampled)
  object-path-set x 5,657,479 ops/sec ±0.95% (93 runs sampled)
  object-set x 2,020,041 ops/sec ±0.92% (91 runs sampled)
  set-value x 11,272,227 ops/sec ±1.36% (88 runs sampled)

  fastest is set-value (by 213% avg)

Running the benchmarks

Clone this library into a local directory:

$ git clone https://github.com/jonschlinkert/set-value.git

Then install devDependencies and run benchmarks:

$ npm install && node benchmark

Comparisons to other libs, or "the list of shame"

These are just a few of the duplicate libraries on NPM.

• bury fails all of the tests. I even wrapped it to have it return the object instead of the value, but with all of that work it still fails the vast majority of tests.
• deep-get-set fails 22 of 26 unit tests.
• deep-object fails 25 of 26 unit tests, completely butchered given objects.
• deep-property fails 17 of 26 unit tests.
• deep-set fails 13 of 26 unit tests.
• deephas fails 17 of 26 unit tests.
• dot-prop fails 9 of 26 unit tests.
• dot2val fails 17 of 26 unit tests.
• es5-dot-prop fails 15 of 26 unit tests.
• getsetdeep fails all unit tests due to this being used improperly in the methods. I was able to patch it by binding the (plain) object to the methods, but it still fails 17 of 26 unit tests.
• lodash.set fails 11 of 26 unit tests.
• object-path-set fails 12 of 26 unit tests.
• object-path fails 16 of 26 unit tests.
• object-set fails 13 of 26 unit tests.
• set-nested-prop fails 24 of 26 unit tests.
• setvalue (this library is almost identical to a previous version of this library)
• Many dozens of others

Others that do the same thing, but use a completely different API

• deep-set-in
• set-deep
• set-deep-prop
• bury
• Many dozens of others

History

v3.0.0

• Added support for a custom split function to be passed on the options.
• Removed support for splitting on brackets, since a custom function can be passed to do this now.

v2.0.0

• Adds support for escaping with double or single quotes. See escaping for examples.
• Will no longer split inside brackets or braces. See bracket support for examples.

If there are any regressions please create a bug report. Thanks!

About

Related projects

You might also be interested in these projects:

• assign-value: Assign a value or extend a deeply nested property of an object using object path… more | homepage
• get-value: Use property paths like 'a.b.c' to get a nested value from an object. Even works… more | homepage
• has-value: Returns true if a value exists, false if empty. Works with deeply nested values using… more | homepage
• merge-value: Similar to assign-value but deeply merges object values or nested values using object path/dot notation. | homepage
• omit-value: Omit properties from an object or deeply nested property of an object using object path… more | homepage
• set-value: Set nested properties on an object using dot notation. | homepage
• union-value: Set an array of unique values as the property of an object. Supports setting deeply… more | homepage
• unset-value: Delete nested properties from an object using dot notation. | homepage

Contributors

Author

Jon Schlinkert

• GitHub Profile
• Twitter Profile
• LinkedIn Profile

License

Copyright © 2021, Jon Schlinkert. Released under the MIT License.

This file was generated by verb-generate-readme, v0.8.0, on September 12, 2021.