Skip to content

Latest commit

 

History

History
188 lines (121 loc) · 4.93 KB

.verb.md

File metadata and controls

188 lines (121 loc) · 4.93 KB
Raw

Heads up!

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

Usage

const set = require('{%= name %}');

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' } } }

options.insert

Allows you to insert values to array, instead of overwriting them.

Type: boolean

Default: undefined

Example

const obj = { path: { to: { array: ['b', 'c'] } } };
set(obj, 'path.to.array.0', 'a', { insert: true });
//=> { path: { to: { array: ['a', 'b', 'c'] } } }

Benchmarks

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

{%= include("./benchmark/stats.md") %}

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][split-string] 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!