flat

Take a nested Javascript object and flatten it, or unflatten an object with delimited keys

flat

Take a nested Javascript object and flatten it, or unflatten an object with delimited keys.

Installation

$ npm install flat

Methods

flatten(original, options)

Flattens the object - it'll return an object one level deep, regardless of how nested the original object was:

var flatten = require('flat')
 
flatten({
    key1: {
        keyA: 'valueI'
    },
    key2: {
        keyB: 'valueII'
    },
    key3: { a: { b: { c: 2 } } }
})
 
// { 
//   'key1.keyA': 'valueI', 
//   'key2.keyB': 'valueII', 
//   'key3.a.b.c': 2 
// } 

unflatten(original, options)

Flattening is reversible too, you can call flatten.unflatten() on an object:

var unflatten = require('flat').unflatten
 
unflatten({
    'three.levels.deep': 42,
    'three.levels': {
        nested: true
    }
})
 
// { 
//     three: { 
//         levels: { 
//             deep: 42, 
//             nested: true 
//         } 
//     } 
// } 

Options

delimiter

Use a custom delimiter for (un)flattening your objects, instead of ..

safe

When enabled, both flat and unflatten will preserve arrays and their contents. This is disabled by default.

var flatten = require('flat')
 
flatten({
    this: [
        { contains: 'arrays' },
        { preserving: {
              them: 'for you'
        }}
    ]
}, {
    safe: true
})
 
// { 
//     'this': [ 
//         { contains: 'arrays' }, 
//         { preserving: { 
//             them: 'for you' 
//         }} 
//     ] 
// } 

object

When enabled, arrays will not be created automatically when using calling unflatten, like so:

unflatten({
    'hello.you.0': 'ipsum',
    'hello.you.1': 'lorem',
    'hello.other.world': 'foo'
}, { object: true })
 
// hello: { 
//     you: { 
//         0: 'ipsum', 
//         1: 'lorem', 
//     }, 
//     other: { world: 'foo' } 
// } 

overwrite

When enabled, existing keys in the unflattened object may be overwritten if they cannot hold a newly encountered nested value:

unflatten({
    'TRAVIS': 'true',
    'TRAVIS_DIR': '/home/travis/build/kvz/environmental'
}, { overwrite: true })
 
// TRAVIS: { 
//     DIR: '/home/travis/build/kvz/environmental' 
// } 

Without overwrite set to true, the TRAVIS key would already have been set to a string, thus could not accept the nested DIR element.

This only makes sense on ordered arrays, and since we're overwriting data, should be used with care.