Skip to content

lukeed/dset

master
Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?
Code

Latest commit

 

Git stats

Files

Permalink
Failed to load latest commit information.
Type
Name
Latest commit message
Commit time
 
 
 
 
src
 
 
 
 
 
 
 
 
 
 
 
 

dset CI codecov

A tiny (194B) utility for safely writing deep Object values~!

For accessing deep object properties, please see dlv.

Using GraphQL? You may want dset/merge – see Merging for more info.

Install

$ npm install --save dset

Modes

There are two "versions" of dset available:

dset

Size (gzip): 194 bytes
Availability: CommonJS, ES Module, UMD

import { dset } from 'dset';

dset/merge

Size (gzip): 288 bytes
Availability: CommonJS, ES Module, UMD

import { dset } from 'dset/merge';

Usage

import { dset } from 'dset';

let foo = { abc: 123 };
dset(foo, 'foo.bar', 'hello');
// or: dset(foo, ['foo', 'bar'], 'hello');
console.log(foo);
//=> {
//=>   abc: 123,
//=>   foo: { bar: 'hello' },
//=> }

dset(foo, 'abc.hello', 'world');
// or: dset(foo, ['abc', 'hello'], 'world');
console.log(foo);
//=> {
//=>   abc: { hello: 'world' },
//=>   foo: { bar: 'hello' },
//=> }

let bar = { a: { x: 7 }, b:[1, 2, 3] };
dset(bar, 'b.1', 999);
// or: dset(bar, ['b', 1], 999);
// or: dset(bar, ['b', '1'], 999);
console.log(bar);
//=> {
//=>   a: { x: 7 },
//=>   b: [1, 999, 3],
//=> }

dset(bar, 'a.y.0', 8);
// or: dset(bar, ['a', 'y', 0], 8);
// or: dset(bar, ['a', 'y', '0'], 8);
console.log(bar);
//=> {
//=>   a: {
//=>     x: 7,
//=>     y: [8],
//=>   },
//=>   b: [1, 999, 3],
//=> }

let baz = {};
dset(baz, 'a.0.b.0', 1);
dset(baz, 'a.0.b.1', 2);
console.log(baz);
//=> {
//=>   a: [{ b: [1, 2] }]
//=> }

Merging

The main/default dset module forcibly writes values at the assigned key-path. However, in some cases, you may prefer to merge values at the key-path. For example, when using GraphQL's @stream and @defer directives, you will need to merge the response chunks into a single object/list. This is why dset/merge exists~!

Below is a quick illustration of the difference between dset and dset/merge:

let input = {
  hello: {
    abc: 123
  }
};

dset(input, 'hello', { world: 123 });
console.log(input);

// via `dset`
//=> {
//=>   hello: {
//=>     world: 123
//=>   }
//=> }

// via `dset/merge`
//=> {
//=>   hello: {
//=>     abc: 123,
//=>     world: 123
//=>   }
//=> }

Immutability

As shown in the examples above, all dset interactions mutate the source object.

If you need immutable writes, please visit clean-set (182B).
Alternatively, you may pair dset with klona, a 366B utility to clone your source(s). Here's an example pairing:

import { dset } from 'dset';
import { klona } from 'klona';

export function deepset(obj, path, val) {
  let copy = klona(obj);
  dset(copy, path, val);
  return copy;
}

API

dset(obj, path, val)

Returns: void

obj

Type: Object

The Object to traverse & mutate with a value.

path

Type: String or Array

The key path that should receive the value. May be in x.y.z or ['x', 'y', 'z'] formats.

Note: Please be aware that only the last key actually receives the value!

Important: New Objects are created at each segment if there is not an existing structure.
However, when integers are encounted, Arrays are created instead!

value

Type: Any

The value that you want to set. Can be of any type!

Benchmarks

For benchmarks and full results, check out the bench directory!

# Node 10.13.0

Validation:
  ✔ set-value
  ✔ lodash/set
  ✔ dset

Benchmark:
  set-value    x 1,701,821 ops/sec ±1.81% (93 runs sampled)
  lodash/set   x   975,530 ops/sec ±0.96% (91 runs sampled)
  dset         x 1,797,922 ops/sec ±0.32% (94 runs sampled)

Related

  • dlv - safely read from deep properties in 120 bytes
  • dequal - safely check for deep equality in 247 bytes
  • klona - quickly "deep clone" data in 200 to 330 bytes
  • clean-set - fast, immutable version of dset in 182 bytes

License

MIT © Luke Edwards

About

A tiny (194B) utility for safely writing deep Object values~!

Resources

License

Stars

Watchers

Forks

Sponsor this project