Skip to content package
safe-json-value v3.0.1 ⛑️ JSON serialization should never fail
node >=18.18.0 2 deps esm types open source
overview readme
license Apache-2.0
deps 2
unpacked 40.1 kB
files 17
node >=18.18.0 $ npm install safe-json-value@3.0.1n npmREADME GitHub-flavored package documentation.
downloads Across all versions.
Download trend unavailable.
compatibility Runtime metadata.
keywords Tagged topics.
bigint circular cycle enumerable exception-handling exceptions getters javascript json library nodejs parsing
versions Latest published Mar 29, 2025
maintainers Registry package owners.
install size Estimated unpacked size across 4 packages.
78.0 kB
Includes dependencies.
dependencies 2 direct dependencies.
⛑️ JSON serialization should never fail.
Features Prevent JSON.stringify() from:
Example import safeJsonValue from 'safe-json-value'
const input = { one: true }
input.self = input
JSON. stringify (input) // Throws due to cycle
const { value, changes } = safeJsonValue (input)
JSON. stringify (value) // '{"one":true}"
console. log (changes) // List of changed properties
// [
// {
// path: ['self'],
// oldValue: <ref *1> { one: true, self: [Circular *1] },
// newValue: undefined,
// reason: 'unsafeCycle'
// }
// ] copy
Install npm install safe-json-value copy This package works in both Node.js >=18.18.0 and
browsers .
API
safeJsonValue(value, options?)
Options Object with the following properties.
maxSize Type : number
Default : 1e7
Big JSON strings can make a process, filesystem operation or network request
crash. maxSize prevents it by setting a maximum
JSON.stringify(value).length.
Additional properties beyond the size limit are omitted . They are
completely removed, not truncated (including strings).
const input = { one: true , two: 'a' . repeat ( 1e6 ) }
JSON. stringify ( safeJsonValue (input, { maxSize: 1e5 }).value) // '{"one":true}" copy
shallow Type : boolean
Default : false
If false, object/array properties are processed recursively. Please note that
cycles are not removed when this is true.
Return value Object with the following properties.
value Copy of the input value after applying all the changes to make
it JSON-safe.
The top-level value itself might be changed (including to undefined) if it
is either invalid JSON or has a toJSON() method .
The value is not serialized to a JSON string. This allows choosing the
serialization format (JSON, YAML, etc.), processing the value, etc.
changes List of changes applied to value . Each item is an
individual change to a specific property. A given property might have multiple
changes, listed in order.
changes[*].path Type : Array<string | symbol | number>
changes[*].oldValue Property value before the change.
changes[*].newValue Property value after the change. undefined means the property was omitted.
changes[*].reason Reason for the change among:
Exceptions : "unsafeCycle" ,
"unsafeBigInt" , "unsafeSize" ,
"unsafeException" ,
"unsafeToJSON" ,
"unsafeGetter"
Invalid descriptors :
"descriptorNotWritable" ,
"descriptorNotConfigurable"
Unexpected types :
"unstableInfinite"
Filtered values : "ignoredFunction" ,
"ignoredUndefined" , "ignoredSymbolValue" ,
"ignoredSymbolKey" ,
"ignoredNotEnumerable" ,
"ignoredArrayProperty"
Unresolved values : "unresolvedToJSON" ,
"unresolvedClass" , "unresolvedGetter"
changes[*].error
Changes This is a list of all possible changes applied to make the value JSON-safe.
Exceptions JSON.stringify() can throw on specific properties. Those are omitted.
Cycles const input = { one: true }
input.self = input
JSON. stringify (input) // Throws due to cycle
JSON. stringify ( safeJsonValue (input).value) // '{"one":true}" copy
Infinite recursion const input = { toJSON : () => ({ one: true , input }) }
JSON. stringify (input) // Throws due to infinite `toJSON()` recursion
JSON. stringify ( safeJsonValue (input).value) // '{"one":true,"input":{...}}" copy
BigInt const input = { one: true , two: 0 n }
JSON. stringify (input) // Throws due to BigInt
JSON. stringify ( safeJsonValue (input).value) // '{"one":true}" copy
Big output const input = { one: true , two: ' \n ' . repeat ( 5e8 ) }
JSON. stringify (input) // Throws due to max string length
JSON. stringify ( safeJsonValue (input).value) // '{"one":true}" copy
Exceptions in toJSON() const input = {
one: true ,
two: {
toJSON : () => {
throw new Error ( 'example' )
},
},
}
JSON. stringify (input) // Throws due to `toJSON()`
JSON. stringify ( safeJsonValue (input).value) // '{"one":true}" copy
Exceptions in getters const input = {
one: true ,
get two () {
throw new Error ( 'example' )
},
}
JSON. stringify (input) // Throws due to `get two()`
JSON. stringify ( safeJsonValue (input).value) // '{"one":true}" copy
Exceptions in proxies const input = new Proxy (
{ one: false },
{
get : () => {
throw new Error ( 'example' )
},
},
)
JSON. stringify (input) // Throws due to proxy
JSON. stringify ( safeJsonValue (input).value) // '{}' copy
Invalid descriptors
Non-writable properties const input = {}
Object. defineProperty (input, 'one' , {
value: true ,
enumerable: true ,
writable: false ,
configurable: true ,
})
input.one = false // Throws: non-writable
const safeInput = safeJsonValue (input).value
safeInput.one = false // Does not throw: now writable copy
Non-configurable properties const input = {}
Object. defineProperty (input, 'one' , {
value: true ,
enumerable: true ,
writable: true ,
configurable: false ,
})
// Throws: non-configurable
Object. defineProperty (input, 'one' , { value: false , enumerable: false })
const safeInput = safeJsonValue (input).value
// Does not throw: now configurable
Object. defineProperty (safeInput, 'one' , { value: false , enumerable: false }) copy
Unexpected types JSON.stringify() changes the types of specific values unexpectedly. Those are
omitted.
NaN and Infinity const input = { one: true , two: Number.NaN, three: Number.POSITIVE_INFINITY }
JSON. stringify (input) // '{"one":true,"two":null,"three":null}"
JSON. stringify ( safeJsonValue (input).value) // '{"one":true}" copy
Invalid array items const input = [ true , undefined, Symbol (), false ]
JSON. stringify (input) // '[true, null, null, false]'
JSON. stringify ( safeJsonValue (input).value) // '[true, false]' copy
Filtered values JSON.stringify() omits some specific types. Those are omitted right away to
prevent any unexpected output.
Functions const input = { one: true , two : () => {} }
JSON. parse (JSON. stringify (input)) // { one: true }
safeJsonValue (input).value // { one: true } copy
undefinedconst input = { one: true , two: undefined }
JSON. parse (JSON. stringify (input)) // { one: true }
safeJsonValue (input).value // { one: true } copy
Symbol values const input = { one: true , two: Symbol () }
JSON. parse (JSON. stringify (input)) // { one: true }
safeJsonValue (input).value // { one: true } copy
Symbol keys const input = { one: true , [ Symbol ()]: true }
JSON. parse (JSON. stringify (input)) // { one: true }
safeJsonValue (input).value // { one: true } copy
Non-enumerable keys const input = { one: true }
Object. defineProperty (input, 'two' , { value: true , enumerable: false })
JSON. parse (JSON. stringify (input)) // { one: true }
safeJsonValue (input).value // { one: true } copy
Array properties const input = [ true ]
input.prop = true
JSON. parse (JSON. stringify (input)) // [true]
safeJsonValue (input).value // [true] copy
Unresolved values JSON.stringify() can transform some values. Those are resolved right away to
prevent any unexpected output.
toJSON()const input = {
toJSON : () => ({ one: true }),
}
JSON. parse (JSON. stringify (input)) // { one: true }
safeJsonValue (input).value // { one: true } copy
Dates const input = { one: new Date () }
JSON. parse (JSON. stringify (input)) // { one: '2022-07-29T14:37:40.865Z' }
safeJsonValue (input).value // { one: '2022-07-29T14:37:40.865Z' } copy
Classes const input = { one: new Set ([]) }
JSON. parse (JSON. stringify (input)) // { one: {} }
safeJsonValue (input).value // { one: {} } copy
Getters const input = {
get one () {
return true
},
}
JSON. parse (JSON. stringify (input)) // { one: true }
safeJsonValue (input).value // { one: true } copy
Proxies const input = new Proxy (
{ one: false },
{
get : () => true ,
},
)
JSON. parse (JSON. stringify (input)) // { one: true }
safeJsonValue (input).value // { one: true } copy
Support Everyone is welcome regardless of personal background. We enforce a
Code of conduct in order to promote a positive and
inclusive environment.
Contributing This project was made with ❤️. The simplest way to give back is by starring and
sharing it online.
If the documentation is unclear or has a typo, please click on the page's Edit
button (pencil icon) and suggest a correction.
If you would like to help us fix a bug or add a new feature, please check our
guidelines . Pull requests are welcome!