flat

flat is a small, dependency-free JavaScript utility that converts nested objects into a single level of dot-delimited keys, and reverses the process to rebuild the original structure from those flat keys. It treats arrays, buffers, typed arrays, and other non-plain-object values as leaf values rather than descending into them, and exposes configurable options for delimiter choice, maximum recursion depth, key transformation, array-safety, and overwrite behavior on conflicting keys.

Beyond the programmatic flatten/unflatten exports, the package ships a flat CLI binary that reads a JSON file (or piped stdin) and prints its flattened form, making it useful for quick inspection of deeply nested config or API response payloads directly from the terminal.

What You Get

• flatten() and unflatten() functions exported as ES modules with full TypeScript type definitions (index.d.ts)
• A flat command-line tool for flattening JSON files or piped stdin from the terminal
• Configurable delimiter, maxDepth, transformKey, safe, object, and overwrite options covering both flatten and unflatten directions
• Built-in prototype-pollution protection in unflatten — __proto__ keys are silently skipped

Common Use Cases

• Converting nested JSON config into KEY.PATH=value pairs for environment-variable-style storage
• Flattening two nested API responses before diffing them so property-level mismatches are readable
• Rebuilding structured objects from flat key-value data pulled from a database row or CLI arguments
• Quick command-line inspection of deeply nested JSON files without writing a parsing script

Under The Hood

Architecture The package is a single ESM module (index.js) exporting two pure functions, flatten and unflatten, built from small private helpers (step, addKeys, getkey, isEmpty, isBuffer) with no internal layering beyond that — there’s no class hierarchy or plugin system to reason about. The cli.js binary is a thin wrapper that reads a file path argument or newline-delimited stdin, parses it as JSON, calls flatten, and writes the result to stdout. Because there’s a single code path with no abstraction boundary, any change to the recursive step() walk in flatten or the delimiter-splitting loop in unflatten immediately affects every consumer and the CLI alike.

Tech Stack Plain JavaScript targeting Node.js 18+ (per engines), shipped as ESM-only ("type": "module") with zero runtime dependencies — the only dependency listed is the standard linter as a devDependency. There is no build or bundling step; the files in package.json’s files array (cli.js, index.js, index.d.ts) are published as-is. The CLI relies solely on Node’s built-in fs, path, and readline modules, and type support for TypeScript consumers comes from a hand-written index.d.ts rather than compiled-down TypeScript source.

Code Quality test/test.js uses Node’s built-in test runner (node --test) with assert.deepStrictEqual across primitives, multi-level nesting, custom delimiters, maxDepth, transformKey, buffers, typed arrays, arrays, prototype-pollution safety, and CLI invocation via child_process.exec — comprehensive coverage relative to the package’s small surface area. Linting is enforced via the standard zero-config ESLint preset as part of the test script, and a GitHub Actions workflow badge in the README indicates CI runs on every push. The core functions do not throw on malformed input — they pass unexpected shapes through silently — and there is no internal type-checking beyond the hand-authored .d.ts declarations (no TypeScript source to enforce types at compile time).

API Design The library’s value is a minimal, symmetrical API — flatten and unflatten mirror each other and share the same delimiter/transformKey semantics — with sensible defaults and enough escape hatches (delimiter, maxDepth, safe, object, overwrite, transformKey) to cover most real-world edge cases without configuration ceremony. Getting started requires a single import and a single function call with no setup. The underlying technique — flattening nested keys via delimiter-joined recursion — is a well-established pattern also implemented by several comparable npm packages, so the package’s strength is in API completeness and ergonomics rather than a novel algorithm.