dot-object

What is dot-object?

The dot-object npm package is a utility for transforming and manipulating JavaScript objects using dot notation. It allows you to easily convert between nested objects and flat objects, set and get values using dot notation, and remove properties from objects.

What are dot-object's main functionalities?

Flattening Objects

This feature allows you to convert a nested object into a flat object using dot notation. The code sample demonstrates how to flatten a nested object.

const Dot = require('dot-object');
const dot = new Dot();
const nested = { a: { b: { c: 1 } } };
const flattened = dot.dot(nested);
console.log(flattened); // { 'a.b.c': 1 }

Unflattening Objects

This feature allows you to convert a flat object with dot notation keys back into a nested object. The code sample demonstrates how to unflatten a flat object.

const Dot = require('dot-object');
const dot = new Dot();
const flattened = { 'a.b.c': 1 };
const nested = dot.object(flattened);
console.log(nested); // { a: { b: { c: 1 } } }

Setting Values

This feature allows you to set a value in an object using dot notation. The code sample demonstrates how to set a nested value in an object.

const Dot = require('dot-object');
const dot = new Dot();
const obj = {};
dot.set('a.b.c', 1, obj);
console.log(obj); // { a: { b: { c: 1 } } }

Getting Values

This feature allows you to get a value from an object using dot notation. The code sample demonstrates how to retrieve a nested value from an object.

const Dot = require('dot-object');
const dot = new Dot();
const obj = { a: { b: { c: 1 } } };
const value = dot.pick('a.b.c', obj);
console.log(value); // 1

Removing Properties

This feature allows you to remove a property from an object using dot notation. The code sample demonstrates how to delete a nested property from an object.

const Dot = require('dot-object');
const dot = new Dot();
const obj = { a: { b: { c: 1 } } };
dot.del('a.b.c', obj);
console.log(obj); // { a: { b: {} } }

Other packages similar to dot-object

flat

The 'flat' package provides similar functionality for flattening and unflattening objects. It is simple to use and focuses on converting nested objects to flat objects and vice versa. Compared to dot-object, 'flat' is more specialized and may be easier to use for basic flattening and unflattening tasks.

lodash

Lodash is a utility library that provides a wide range of functions for manipulating objects, arrays, and other data structures. It includes methods for deep setting, getting, and removing properties using dot notation. While Lodash offers more comprehensive functionality beyond object manipulation, it can be more complex to use compared to dot-object.

object-path

The 'object-path' package provides utilities for accessing and manipulating deep properties of objects using dot notation. It offers similar features to dot-object, such as setting, getting, and deleting properties. 'object-path' is focused on deep property manipulation and is a good alternative to dot-object for these specific tasks.

README

Dot-Object

Dot-Object makes it possible to transform javascript objects using dot notation.

Installation

Install from npm:

  npm install dot-object --save

Install from bower:

  bower install dot-object --save

Download

• Development version: https://unpkg.com/dot-object/dist/dot-object.js Uncompressed with Comments
• Production version: https://unpkg.com/dot-object/dist/dot-object.min.js Minified

Usage

Move a property within one object to another location

var dot = require('dot-object');

var obj = {
  'first_name': 'John',
  'last_name': 'Doe'
};

dot.move('first_name', 'contact.firstname', obj);
dot.move('last_name', 'contact.lastname', obj);

console.log(obj);

{
  contact: {
    firstname: 'John',
    lastname: 'Doe'
  }
}

Copy property from one object to another

var dot = require('dot-object');

var src = {
  name: 'John',
  stuff: {
    phone: {
      brand: 'iphone',
      version: 6
    }
  }
};

var tgt = {name: 'Brandon'};

dot.copy('stuff.phone', 'wanna.haves.phone', src, tgt);

console.log(tgt);

{
  name: 'Brandon',
  wanna: {
    haves: {
      phone: {
        brand: 'iphone',
        version: 6
      }
    }
  }
}

Transfer property from one object to another

Does the same as copy but removes the value from the source object:

dot.transfer('stuff.phone', 'wanna.haves.phone', src, tgt);

// src: {"name":"John","stuff":{}}
// tgt: {"name":"Brandon","wanna":{"haves":{"phone":{"brand":"iphone","version":6}}}

Expand to an object

var dot = require('dot-object');

var row = {
  'id': 2,
  'contact.name.first': 'John',
  'contact.name.last': 'Doe',
  'contact.email': '[e-mail]',
  'contact.info.about.me': 'classified',
  'devices[0]': 'mobile',
  'devices[1]': 'laptop',
  'some.other.things.0': 'this',
  'some.other.things.1': 'that'
};

dot.object(row);

console.log(row);

{
  "id": 2,
  "contact": {
    "name": {
      "first": "John",
      "last": "Doe"
    },
    "email": "[e-mail]",
    "info": {
      "about": {
        "me": "classified"
      }
    }
  },
  "devices": [
    "mobile",
    "laptop"
  ],
  "some": {
    "other": {
      "things": [
        "this",
        "that"
      ]
    }
  }
}

To convert manually per string use:

var dot = require('dot-object');

var tgt = { val: 'test' };
dot.str('this.is.my.string', 'value', tgt);

console.log(tgt);

{
  "val": "test",
  "this": {
    "is": {
      "my": {
        "string": "value"
      }
    }
  }
}

Pick a value using dot notation:

Picks a value from the object without removing it.

var dot = require('dot-object');

var obj = {
 some: {
   nested: {
     value: 'Hi there!'
   }
 }
};

var val = dot.pick('some.nested.value', obj);
console.log(val);

Hi there!

Delete/Remove a value using dot notation:

Remove and delete mostly behave the same, but in case of a path addressing array items:

• delete will re-index the array.
• remove will retain array indexes

var dot = require('dot-object');

var obj = {
 a: 'Hi There!',
 nested: {
   array: [ 
     'Veni',
     'Vidi',
     'Vici',
   ]
 }
};

var val = dot.delete('a', obj);
console.log(val);

Hi There!

// To remove an item and directly update any array indexes use:
var val = dot.delete('nested.array[1]', obj);
console.log(val);

Vidi

// Remove a value but retain array indexes. 
var val = dot.remove('nested.array[1]', obj);

// To remove multiple paths at once:
var val = dot.remove(['nested.array[0]', 'nested.array[2]'], obj);

Using modifiers

You can use modifiers to translate values on the fly.

This example uses the underscore.string library.

var dot = require('dot-object');

var _s = require('underscore.string');

var row = {
  'nr': 200,
  'doc.name': '    My Document   '
};

var mods = {
  "doc.name": [_s.trim, _s.underscored],
};

dot.object(row, mods);

console.log(row);

{
  "nr": 200,
  "doc": {
    "name": "my_document"
  }
}

Or using .str() directy:

var dot = require('dot-object');
var _s = require('underscore.string');
var obj = { id: 100 };

// use one modifier
dot.str('my.title', 'this is my title', obj, _s.slugify);

// multiple modifiers
dot.str('my.title', '   this is my title  ', obj, [_s.trim, _s.slugify]);

console.log(obj);

Result:

{
  "id": 100,
  "my": {
    "title": "this-is-my-title"
  }
}

Transform object

var dot = require('dot-object');

var source = {
  "id": 1,
  "contact": {
    "firstName": "John",
    "lastName": "Doe",
    "email": "[e-mail]",
  }
}

var recipe = {
  'id': 'nr',
  'contact.firstName': 'name.first',
  'contact.lastName': 'name.last',
  'contact.email': 'email'
};

var tgt = {}
dot.transform(recipe, source, tgt);

// OR

var tgt = dot.transform(recipe, source);

console.log(tgt);
{
  "nr": 1,
  "name": {
    "first": "John",
    "last": "Doe"
  },
  "email": "[e-mail]"
}

Convert object to dotted-key/value pair

var dot = require('dot-object');

var obj = {
  id: 'my-id',
  nes: { ted: { value: true } },
  other: { nested: { stuff: 5 } },
  some: { array: ['A', 'B'] }
};

var tgt = dot.dot(obj);

// or

var tgt = {};
dot.dot(obj, tgt);

console.log(tgt);

Result:

{
  "id": "my-id",
  "nes.ted.value": true,
  "other.nested.stuff": 5,
  "some.array[0]": "A",
  "some.array[1]": "B"
}

Keep array

Set keepArray to true.

var dot = require('dot-object');

var obj = {
  id: 'my-id',
  other: [1, 2, 3],
  some: { array: ['A', 'B'] }
};

dot.keepArray = true;
var tgt = dot.dot(obj);

console.log(tgt);

Result:

{
  "id": "my-id",
  "other": [1, 2, 3],
  "some.array": ["A", "B"]
}

Using a different separator

If you do not like dot notation, you are free to specify a different separator.

var Dot = require('dot-object');

var dot = new Dot('->');

var _s = require('underscore.string');

var row = {
  'nr': 200,
  'doc->name': '    My Document   '
};

var mods = {
  "doc->name": [_s.trim, _s.underscored],
};

dot.object(row, mods);

console.log(row);

{
  "nr": 200,
  "doc": {
    "name": "my_document"
  }
}

Transforming SQL results to JSON

SQL translation on the fly:

 // TODO

Copyright © 2013 Rob Halff, released under the MIT license

Changelog

2024-04-19 Version 2.1.5

• [a23221d367408] - Add LICENSE property to package.json (Fixed by denniskim #54)