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.