flat

To use flat in your project, install it using npm:

$ npm install flat

Both flatten and unflatten accept an options object to customize behavior. Available options include:

• delimiter: Use a custom string instead of . to separate keys.
• safe: When true, preserves arrays and their contents instead of flattening them. Disabled by default.
• object: When true (used with unflatten), arrays will not be created automatically; instead, numeric keys will be treated as object properties.
• overwrite: When true (used with unflatten), existing keys may be overwritten if they cannot hold a newly encountered nested value.
• maxDepth: The maximum number of nested levels to flatten.
• transformKey: A function applied to each part of a key before and after the (un)flattening process.

The maxDepth option limits how many levels of nesting the flatten method will process.

import { flatten } from 'flat'

flatten({
    key1: {
        keyA: 'valueI'
    },
    key2: {
        keyB: 'valueII'
    },
    key3: { a: { b: { c: 2 } } }
}, { maxDepth: 2 })

// {
//   'key1.keyA': 'valueI',
//   'key2.keyB': 'valueII',
//   'key3.a': { b: { c: 2 } }
// }

By default, flat flattens arrays. Setting { safe: true } ensures arrays and their contents are preserved in the resulting object.

import { flatten } from 'flat'

flatten({
    this: [
        { contains: 'arrays' },
        { preserving: { 
              them: 'for you' 
        }}
    ]
}, {
    safe: true
})

// {
//     'this': [
//         { contains: 'arrays' },
//         { preserving: {
//             them: 'for you'
//         }}
//     ]
// }

When calling unflatten, setting { object: true } prevents the creation of arrays for numeric keys, treating them as standard object properties instead.

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

// hello: {
//     you: {
//         0: 'ipsum',
//         1: 'lorem',
//     },
//     other: { world: 'foo' }
// }

If an existing key in the unflattened object is a primitive (like a string) but a new nested value needs to be placed at that path, setting { overwrite: true } allows the primitive to be replaced by the new nested object.

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

// TRAVIS: {
//     DIR: '/home/travis/build/kvz/environmental'
// }

The flatten(original, options) method takes a nested Javascript object and returns a new object that is one level deep. Nested keys are joined using a delimiter (defaulting to .).

import { flatten } from 'flat'

flatten({
    key1: {
        keyA: 'valueI'
    },
    key2: {
        keyB: 'valueII'
    },
    key3: { a: { b: { c: 2 } } }
})

// {
//   'key1.keyA': 'valueI',
//   'key2.keyB': 'valueII',
//   'key3.a.b.c': 2
// }

The unflatten(original, options) method is the reverse of flatten. It takes an object with delimited keys and reconstructs the original nested structure.

import { unflatten } from 'flat'

unflatten({
    'three.levels.deep': 42,
    'three.levels': {
        nested: true
    }
})

// {
//     three: {
//         levels: {
//             deep: 42,
//             nested: true
//         }
//     }
// }

The flat package can be used as a command-line tool to process JSON files or stdin.

Using npx:

npx flat foo.json

Global installation:

npm i -g flat && flat foo.json

Using stdin:

cat foo.json | flat

The unflatten(target, opts) function takes a flat object with delimited keys and reconstructs the original nested object structure.

If the input target is not a plain object (e.g., it is a Buffer or a primitive), the function returns the target as-is. It also includes safety checks to prevent prototype pollution by ignoring __proto__ keys.