Flatten JSON-like values into dot-path key/value pairs or unFlatten them back into nested objects, with support for arrays, dates, and customizable options.
npm install flatten-to-key-valueFlatten 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.
``bash`
npm i flatten-to-key-valueor
pnpm add flatten-to-key-valueor
yarn add flatten-to-key-value
`ts
import { flattenToKeyValue, unflattenKeyValue } from "flatten-to-key-value";
const contacts = [
{
firstname: "Jane",
lastName: "Doe",
email: "jane.doe@example.com",
phoneNumber: "+61 400 000 000",
},
{
firstname: "Mark",
lastName: "Smith",
email: "mark.smith@example.com",
phoneNumber: null,
},
];
const flat = flattenToKeyValue(contacts);
console.log(flat);
/*
{
firstname: "Jane,Mark",
lastName: "Doe,Smith",
email: "jane.doe@example.com,mark.smith@example.com",
phoneNumber: "+61 400 000 000,null"
}
*/
const restored = unflattenKeyValue(flat);
console.log(restored);
/*
[
{
firstname: "Jane",
lastName: "Doe",
email: "jane.doe@example.com",
phoneNumber: "+61 400 000 000"
},
{
firstname: "Mark",
lastName: "Smith",
email: "mark.smith@example.com",
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.
`js
const {
flattenToKeyValue,
unflattenKeyValue,
} = require("flatten-to-key-value");
const out = flattenToKeyValue({ a: { b: [1, 2] } });
const back = unflattenKeyValue(out);
`
`ts
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
function unflattenKeyValue(
input: Record
opts?: FlattenOptions
): unknown;
`
- Flatten
- Top-level primitives result in an empty object (no anonymous key).
- Circular references fall back to String(v) for non-serializable values.dedupeArrayValues: true
- 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 to remove repeats.
- Unflatten
- Keys are split by delimiter to rebuild objects.joiner
- Joined values are split by back into arrays.null
- 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, , undefined, Date objects, or JSON where possible.
- Single-element arrays are collapsed back to scalars.
`bash``
pnpm i
pnpm test
pnpm build
MIT