Flattie Object Flattening Utility

1.1.1 · active · verified Sun Apr 19

Flattie is a minimalist and highly performant JavaScript utility for recursively flattening nested objects and arrays into a single-depth object. Currently at version 1.1.1, the library maintains a stable release cadence with incremental patches. Its core differentiators include its extremely small bundle size (203B), demonstrated speed via benchmarks against alternatives like `flat` and `flatten-object`, and customizable behavior for key concatenation via a 'glue' string. By default, it automatically omits nullish values (`null`, `undefined`) from the flattened output, a feature that can be toggled. It also ships with TypeScript type definitions, providing a robust developer experience. Its counterpart, `nestie`, provides the reverse operation (expanding flattened objects).

Common errors

```
TypeError: flattie is not a function
```
cause Attempting to import `flattie` as a default export or using `require()` without destructuring in a CommonJS environment. The `flattie` function is a named export.

fix For ESM, use `import { flattie } from 'flattie';`. For CommonJS, use `const { flattie } = require('flattie');`.
```
Object.prototype.hasOwnProperty.call is not a function
```
cause This error typically indicates an issue with an object not being a plain object or potential environment incompatibility, though less common with `flattie`'s focused scope. It might occur if `input` is a primitive or a highly custom object lacking standard `Object.prototype` methods.

fix Ensure the `input` provided to `flattie` is a valid JavaScript object or array. Verify your Node.js version is `>=8` as specified in the package engines.

Warnings

gotcha By default, `null` and `undefined` values are automatically excluded from the flattened output. This behavior might be unexpected if you intend to preserve all original data points.
Fix: To retain nullish values, pass `true` as the third argument to the `flattie` function: `flattie(input, glue, true)`.
gotcha Flattie always returns a new object, even if the input is an array. Array elements will be mapped to keys using their numerical indices combined with the specified glue string.
Fix: Be aware that the output format is consistently an object. If an array is desired, a post-processing step to convert the flattened object back into an array structure would be necessary.
gotcha While `null` and `undefined` are purged, other 'empty' or special values like empty strings (`''`) or `NaN` are preserved in the output by default.
Fix: If specific handling for empty strings, `NaN`, or other non-nullish but undesirable values is required, implement custom pre-processing on the input or post-processing on the flattened output.

Install

npm install flattie npm
yarn add flattie yarn
pnpm add flattie pnpm

Imports

flattie
wrong:
```
import flattie from 'flattie';
const flattie = require('flattie');
```
correct:
```
import { flattie } from 'flattie';
```
The primary flattening function is a named export. It is not a default export, and CommonJS `require` should use destructuring.

Quickstart

Demonstrates basic object flattening, custom glue usage, and how to retain nullish values.

import { flattie } from 'flattie';

const nestedObject = {
  user: 'alice',
  profile: {
    email: 'alice@example.com',
    settings: {
      theme: 'dark',
      notifications: true,
      preferences: [
        { id: 1, value: 'optionA' },
        { id: 2, value: null },
        { id: 3, value: 'optionC' }
      ]
    }
  },
  status: null,
  tags: ['admin', 'premium']
};

// Flatten the object with default glue ('.') and nullish purging (true)
const flatDefault = flattie(nestedObject);
console.log('Default Flattened:', flatDefault);

// Flatten the object keeping nullish values
const flatKeepNullish = flattie(nestedObject, '.', true);
console.log('Flattened (keeping nullish):', flatKeepNullish);

// Flatten the object with a custom glue
const flatCustomGlue = flattie(nestedObject, '__');
console.log('Flattened (custom glue):', flatCustomGlue);

view raw JSON →