flatten-to-key-value

Flatten or unflatten any JSON-like value.

• Flatten: turn objects into { "a.b.c": "value", ... }.
• Unflatten: rebuild nested structures from flattened key/value pairs.
• Arrays of primitives aggregate into a single key and are joined (default ,), preserving null placeholders.
• Arrays of objects merge matching leaf paths across elements and rebuild the original array of objects when every key contains the same number of values.
• Dates are serialized to ISO strings and restored back as Date objects when possible.
• Optional deduping, key sorting, delimiter and joiner customization.
• Opt-in preserveArrayStructure keeps numeric indexes in the flattened output when you do not want values to be merged.

Install

npm i flatten-to-key-value
# or
pnpm add flatten-to-key-value
# or
yarn add flatten-to-key-value

Usage

ESM

import { flattenToKeyValue, unflattenKeyValue } from "flatten-to-key-value";

const contacts = [
  {
    firstname: "Jane",
    lastName: "Doe",
    email: "[email protected]",
    phoneNumber: "+61 400 000 000",
  },
  {
    firstname: "Mark",
    lastName: "Smith",
    email: "[email protected]",
    phoneNumber: null,
  },
];

const flat = flattenToKeyValue(contacts);
console.log(flat);
/*
{
  firstname: "Jane,Mark",
  lastName: "Doe,Smith",
  email: "[email protected],[email protected]",
  phoneNumber: "+61 400 000 000,null"
}
*/

const restored = unflattenKeyValue(flat);
console.log(restored);
/*
[
  {
    firstname: "Jane",
    lastName: "Doe",
    email: "[email protected]",
    phoneNumber: "+61 400 000 000"
  },
  {
    firstname: "Mark",
    lastName: "Smith",
    email: "[email protected]",
    phoneNumber: null
  }
]
*/

// Need indexes instead of merged values?
const preserved = flattenToKeyValue(contacts, { preserveArrayStructure: true });

When only some keys contain joined values, unflattenKeyValue leaves them as arrays alongside scalar fields so that no information is lost. Use the options object to tweak the delimiter, joiner, sorting, or to dedupe repeated values before joining.

CommonJS

const {
  flattenToKeyValue,
  unflattenKeyValue,
} = require("flatten-to-key-value");

const out = flattenToKeyValue({ a: { b: [1, 2] } });
const back = unflattenKeyValue(out);

API

type FlattenOptions = {
  delimiter?: string; // default "."
  joiner?: string; // default ","
  includeNullUndefined?: boolean; // default false (skips null/undefined)
  dedupeArrayValues?: boolean; // default false
  sortKeys?: boolean; // default false
  preserveArrayStructure?: boolean; // default false (keeps numeric indexes)
};

function flattenToKeyValue(
  input: unknown,
  opts?: FlattenOptions
): Record<string, string>;

function unflattenKeyValue(
  input: Record<string, string>,
  opts?: FlattenOptions
): unknown;

Notes

• Flatten

  • Top-level primitives result in an empty object (no anonymous key).
  • Circular references fall back to String(v) for non-serializable values.
  • Arrays of primitives: each element is collected under the same key and joined at the end.
  • Arrays of objects: leaf paths are merged across elements—use dedupeArrayValues: true to remove repeats.

• Unflatten

  • Keys are split by delimiter to rebuild objects.
  • Joined values are split by joiner back into arrays.
  • If every flattened key splits into the same number of values (> 1), the output is rebuilt as an array of objects in that order.
  • Mixed single/multi-value keys fall back to objects with arrays so scalars stay scalars.
  • String values are parsed into numbers, booleans, null, undefined, Date objects, or JSON where possible.
  • Single-element arrays are collapsed back to scalars.

Development

pnpm i
pnpm test
pnpm build

License

MIT