{"id":11975,"library":"safe-flat","title":"Safe Flat Utilities","description":"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.","status":"active","version":"2.1.0","language":"javascript","source_language":"en","source_url":"https://github.com/jessie-codes/safe-flat","tags":["javascript","flat","flatten","json","nested","object","safe","serialize","unflatten","typescript"],"install":[{"cmd":"npm install safe-flat","lang":"bash","label":"npm"},{"cmd":"yarn add safe-flat","lang":"bash","label":"yarn"},{"cmd":"pnpm add safe-flat","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"ESM import for modern JavaScript modules. CommonJS `require` also supported.","wrong":"const { flatten } = require('safe-flat');","symbol":"flatten","correct":"import { flatten } from 'safe-flat';"},{"note":"ESM import for modern JavaScript modules. CommonJS `require` also supported.","wrong":"const { unflatten } = require('safe-flat');","symbol":"unflatten","correct":"import { unflatten } from 'safe-flat';"},{"note":"Import type definitions for TypeScript projects.","symbol":"Types","correct":"import type { FlattenedObject, UnflattenedObject } from 'safe-flat';"}],"quickstart":{"code":"import { flatten, unflatten } from 'safe-flat';\n\nconst original = {\n    a: {\n        b: {\n            c: [{ val: 'one' }, { val: 'two' }],\n            d: 'three'\n        },\n        e: 'four',\n    }\n};\noriginal.a.b.f = original.a.b; // Introduce a circular reference\noriginal.a.b.c.push(original.a); // Another circular reference\n\nconsole.log('Original Object:', JSON.stringify(original, null, 2));\n\nconst flat = flatten(original);\nconsole.log('\\nFlattened Object (default delimiter):', JSON.stringify(flat, null, 2));\n\nconst underscoreFlat = flatten(original, '_');\nconsole.log('\\nFlattened Object (underscore delimiter):', JSON.stringify(underscoreFlat, null, 2));\n\nconst unflat = unflatten(flat);\nconsole.log('\\nUnflattened Object:', JSON.stringify(unflat, null, 2));\n\n// Note: Circular references are not re-created; '[Circular]' strings remain.\n","lang":"typescript","description":"Demonstrates how to flatten a nested object (including circular references) and then unflatten it back, using both default and custom delimiters."},"warnings":[{"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.","message":"The `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.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Always ensure the `delimiter` argument to `unflatten` is identical to the one used for `flatten`.","message":"Consistency 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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"While `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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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.","cause":"The delimiter used in `unflatten` does not match the delimiter used during `flatten`, or the input flattened object structure is not as expected.","error":"TypeError: Cannot read properties of undefined (reading '0') / TypeError: Cannot set properties of undefined (setting 'b') / Object reconstruction incorrect"},{"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.","cause":"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.","error":"Unflattened object contains `\"[Circular]\"` strings instead of reconstructed object references."}],"ecosystem":"npm"}