flattie

What is flattie?

The flattie npm package is a utility for flattening and unflattening nested objects. It is useful for transforming complex nested structures into simpler key-value pairs and vice versa.

What are flattie's main functionalities?

Flattening Objects

This feature allows you to convert a nested object into a flat object with dot-separated keys.

const flattie = require('flattie');
const nestedObject = { a: { b: { c: 1 } }, d: 2 };
const flatObject = flattie(nestedObject);
console.log(flatObject); // { 'a.b.c': 1, d: 2 }

Unflattening Objects

This feature allows you to convert a flat object with dot-separated keys back into a nested object.

const flattie = require('flattie');
const flatObject = { 'a.b.c': 1, d: 2 };
const nestedObject = flattie.unflatten(flatObject);
console.log(nestedObject); // { a: { b: { c: 1 } }, d: 2 }

Other packages similar to flattie

flat

The 'flat' package provides similar functionality for flattening and unflattening objects. It offers more customization options, such as custom delimiters and safe mode to handle arrays.

flatnest

The 'flatnest' package also provides utilities for flattening and unflattening objects. It is designed to be simple and lightweight, similar to flattie, but with fewer configuration options.

flatten

The 'flatten' package is another alternative for flattening nested objects. It focuses on simplicity and ease of use, similar to flattie, but does not support unflattening.

README

flattie

A tiny (203B) and fast utility to flatten an object with customizable glue

This module recursively squashes an Object/Array. The output is a flat object – AKA, it has a single level of depth.

By default, the . character is used to glue/join layers' keys together. This is customizable.

Finally, by default, any keys with nullish values (null and undefined) are not included in the return object.

Install

$ npm install --save flattie

Usage

import { flattie } from 'flattie';

flattie({
  a: 'hi',
  b: {
    a: null,
    b: ['foo', '', null, 'bar'],
    d: 'hello',
    e: {
      a: 'yo',
      b: undefined,
      c: 'sup',
      d: 0,
      f: [
        { foo: 123, bar: 123 },
        { foo: 465, bar: 456 },
      ]
    }
  },
  c: 'world'
});
// {
//   'a': 'hi',
//   'b.b.0': 'foo',
//   'b.b.1': '',
//   'b.b.3': 'bar',
//   'b.d': 'hello',
//   'b.e.a': 'yo',
//   'b.e.c': 'sup',
//   'b.e.d': 0,
//   'b.e.f.0.foo': 123,
//   'b.e.f.0.bar': 123,
//   'b.e.f.1.foo': 465,
//   'b.e.f.1.bar': 456,
//   'c': 'world'
// }

Note: null and undefined values are purged by default.

API

flattie(input, glue?, keepNullish?)

Returns: Object

Returns a new object with a single level of depth.

Important: An object is always returned despite input type.

input

Type: Object|Array

The object to flatten.

glue

Type: String
Default: .

A string used to join parent key names to nested child key names.

const foo = { bar: 123 };

flattie({ foo }); //=> { 'foo.bar': 123 }
flattie({ foo }, '???'); //=> { 'foo???bar': 123 }

keepNullish

Type: Boolean
Default: false

Whether or not null and undefined values should be kept.

// Note: Applies to Objects too
const foo = ['hello', null, NaN, undefined, /*hole*/, 'world'];

flattie({ foo });
//=> {
//=>   'foo.0': 'hello',
//=>   'foo.2': NaN,
//=>   'foo.5': 'world'
//=> }

flattie({ foo }, '.', true);
//=> {
//=>   'foo.0': 'hello',
//=>   'foo.1': null,
//=>   'foo.2': NaN,
//=>   'foo.3': undefined,
//=>   'foo.4': undefined,
//=>   'foo.5': 'world'
//=> }

Benchmarks

Running on Node.js v10.13.0

Load Time:
  flat             1.047ms
  flatten-object   1.239ms
  flat-obj         0.997ms
  flattie          0.258ms

Validation:
  ✔ flat
  ✔ flatten-object
  ✔ flat-obj
  ✔ flattie

Benchmark:
  flat               x 186,487 ops/sec ±1.28% (86 runs sampled)
  flatten-object     x 199,476 ops/sec ±1.01% (93 runs sampled)
  flat-obj           x 393,574 ops/sec ±1.41% (95 runs sampled)
  flattie            x 909,734 ops/sec ±0.82% (93 runs sampled)

License

MIT © Luke Edwards