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

``bash
npm i flatten-to-key-value


or

pnpm add flatten-to-key-value

or

yarn add flatten-to-key-value
`

Usage

$3

`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.

$3

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

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

API

`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;
`

$3

- 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

`bash
pnpm i
pnpm test
pnpm build
``

License

MIT