dset

What is dset?

The dset npm package is a tiny utility for safely setting deep values in JavaScript objects. It is designed to be fast and efficient, making it ideal for performance-sensitive applications.

What are dset's main functionalities?

Set deep values

This feature allows you to set a value deep within an object using a dot-separated string path. The dset function will create any necessary intermediate objects.

const dset = require('dset');
let obj = {};
dset(obj, 'a.b.c', 42);
console.log(obj); // { a: { b: { c: 42 } } }

Array index support

dset supports setting values within arrays by using bracket notation in the path string. This allows for complex nested structures involving both objects and arrays.

const dset = require('dset');
let obj = {};
dset(obj, 'a.b[0].c', 42);
console.log(obj); // { a: { b: [ { c: 42 } ] } }

Custom separator

You can specify a custom separator for the path string, allowing for flexibility in how paths are defined.

const dset = require('dset');
let obj = {};
dset(obj, 'a/b/c', 42, '/');
console.log(obj); // { a: { b: { c: 42 } } }

Other packages similar to dset

lodash.set

Lodash is a popular utility library that provides a set function for setting deep values in objects. While lodash.set is more feature-rich and part of a larger library, it is also larger in size compared to dset.

dot-prop

dot-prop is another utility for managing deep properties in JavaScript objects. It offers similar functionality to dset but includes additional features like getting and deleting properties. However, it is slightly larger in size.

set-value

set-value is a utility for setting nested values in objects using dot notation. It is similar in functionality to dset but includes additional options for customizing behavior. It is also larger in size compared to dset.

README

dset

A tiny (197B) 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): 197 bytes
Availability: CommonJS, ES Module, UMD

import { dset } from 'dset';

dset/merge

Size (gzip): 307 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