safe-flat

library2.1.0jsnpmunverified

safe-flat is a JavaScript/TypeScript utility library designed for safely flattening and unflattening deeply nested objects. Its primary function, `flatten`, converts a multi-level object into a single-level object, using a configurable delimiter (defaulting to '.'). A key feature is its robust handling of circular references, which it replaces with the `[Circular]` string during flattening to prevent infinite recursion and serialization issues. The companion function, `unflatten`, reconstructs the original nested object structure from a flattened representation, treating `[Circular]` markers as literal string values. The current stable version, 2.1.0, is distributed with TypeScript types, enhancing developer experience. It appears to have a stable, though infrequent, release cadence, focusing on reliability for object serialization and deserialization tasks by mitigating common pitfalls like circular references.

serialization

npm install safe-flat

github ↗package ↗

INSTALL

IMPORT

SIG · SAFE-FLAT

safe-flat

serializationjavascriptv2.1.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

flatten

✓ import { flatten } from 'safe-flat';

✗ const { flatten } = require('safe-flat');

ESM import for modern JavaScript modules. CommonJS `require` also supported.

unflatten

✓ import { unflatten } from 'safe-flat';

✗ const { unflatten } = require('safe-flat');

ESM import for modern JavaScript modules. CommonJS `require` also supported.

Types

✓ import type { FlattenedObject, UnflattenedObject } from 'safe-flat';

Import type definitions for TypeScript projects.

Demonstrates how to flatten a nested object (including circular references) and then unflatten it back, using both default and custom delimiters.

import { flatten, unflatten } from 'safe-flat'; const original = { a: { b: { c: [{ val: 'one' }, { val: 'two' }], d: 'three' }, e: 'four', } }; original.a.b.f = original.a.b; // Introduce a circular reference original.a.b.c.push(original.a); // Another circular reference console.log('Original Object:', JSON.stringify(original, null, 2)); const flat = flatten(original); console.log('\nFlattened Object (default delimiter):', JSON.stringify(flat, null, 2)); const underscoreFlat = flatten(original, '_'); console.log('\nFlattened Object (underscore delimiter):', JSON.stringify(underscoreFlat, null, 2)); const unflat = unflatten(flat); console.log('\nUnflattened Object:', JSON.stringify(unflat, null, 2)); // Note: Circular references are not re-created; '[Circular]' strings remain.

Debug

Known issues

gotchaThe `flatten` function replaces circular references with the literal string `[Circular]` to prevent infinite loops. When `unflatten` is used, these `[Circular]` markers are treated as plain string values and the original circular object references are NOT reconstructed. This is by design but can be misunderstood by users expecting full deserialization of circular graphs.

fix

Be aware of this design choice. If true circular reference reconstruction is required, `safe-flat` is not the appropriate tool; consider a custom serialization/deserialization solution.

affects: >=1.0.0

gotchaConsistency in the `delimiter` is crucial. If `flatten` is called with a custom delimiter (e.g., '_') and `unflatten` is later called without specifying that same delimiter (thus using the default '.'), the `unflatten` operation will fail to correctly reconstruct the object structure, resulting in a malformed output.

fix

Always ensure the `delimiter` argument to `unflatten` is identical to the one used for `flatten`.

affects: >=1.0.0

gotchaWhile `safe-flat` handles circular references, it does not perform deep cloning or custom serialization for other complex nested types (e.g., `Date` objects, `RegExp`, custom class instances). These values will be preserved directly if they are terminal leaves in the flattened structure, but `safe-flat` doesn't provide specific mechanisms for their custom serialization or deserialization.

fix

For specific serialization needs of complex types beyond standard JSON primitives and circular reference handling, additional pre- or post-processing steps or a different library might be necessary.

affects: >=1.0.0

Errors

Common errors & fixes

TypeError: Cannot read properties of undefined (reading '0') / TypeError: Cannot set properties of undefined (setting 'b') / Object reconstruction incorrect

The delimiter used in `unflatten` does not match the delimiter used during `flatten`, or the input flattened object structure is not as expected.

fix

Verify that the `delimiter` argument passed to `unflatten` is the same as the one used for `flatten`. Inspect the flattened object's keys to ensure they follow the expected delimited path format.

Unflattened object contains `"[Circular]"` strings instead of reconstructed object references.

This is the intended behavior of `safe-flat`. The library does not reconstruct circular references during the `unflatten` operation; it preserves `[Circular]` as a literal string.

fix

No fix within `safe-flat` itself. If true circular reference restoration is a requirement, an alternative serialization/deserialization strategy or library must be used.

Upgrade

Version history

2.1.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

10 hits · last 30 days

node

Resources

githubhttps://github.com/jessie-codes/safe-flat ↗

packagehttps://www.npmjs.com/package/safe-flat ↗