is-json-value
v3.0.0
Published
Check if a value is valid JSON
Downloads
493
Maintainers
Readme
Check if a value is valid JSON.
Hire me
Please reach out if you're looking for a Node.js API or CLI engineer (11 years of experience). Most recently I have been Netlify Build's and Netlify Plugins' technical lead for 2.5 years. I am available for full-time remote positions.
Features
- Detects many types of invalid values with JSON
- Returns warning messages to throw or log
- Returns invalid properties' path and value
Example
import isJsonValue from 'is-json-value'
const input = { one: true, two: { three: Symbol() } }
input.self = input
// Throws due to cycle with 'self'.
// Also, 'two.three' would be omitted since it has an invalid JSON type.
JSON.stringify(input)
const warnings = isJsonValue(input)
const isValidJson = warnings.length === 0 // false
console.log(warnings)
// [
// {
// message: 'Property "two.three" must not be a symbol.',
// path: ['two', 'three'],
// value: Symbol(),
// reason: 'ignoredSymbolValue'
// },
// {
// message: 'Property "self" must not be a circular value.',
// path: ['self'],
// value: <ref *1> { one: true, two: [Object], self: [Circular *1] },
// reason: 'unsafeCycle'
// }
// ]
if (!isValidJson) {
// Error: Property "two.three" must not be a symbol.
throw new Error(warnings[0].message)
}
Install
npm install is-json-value
This package works in both Node.js >=18.18.0 and browsers.
This is an ES module. It must be loaded using
an import
or import()
statement,
not require()
. If TypeScript is used, it must be configured to
output ES modules,
not CommonJS.
API
isJsonValue(input)
input
any
Return value: Warning[]
Returns an array of warnings. If input
is valid to serialize as
JSON, that array is empty.
Warning
Each warning is an object indicating that a specific property is invalid to serialize as JSON. The same property might have multiple warnings.
message
Type: string
Warning message, like 'Property "example" must not be a symbol.'
path
Type: Array<string | symbol | number>
Path to the invalid property. Empty array if this is the top-level value.
value
Type: unknown
Value of the invalid property.
reason
Type: string
Reason for the warning among:
- Invalid type:
"ignoredFunction"
,"ignoredUndefined"
,"ignoredSymbolValue"
,"ignoredSymbolKey"
,"unstableInfinite"
,"unresolvedClass"
,"ignoredNotEnumerable"
,"ignoredArrayProperty"
- Throws an exception:
"unsafeCycle"
,"unsafeBigInt"
,"unsafeSize"
,"unsafeException"
,"unsafeToJSON"
,"unsafeGetter"
Warnings
This is the list of possible warnings.
Invalid types
JSON only supports booleans, numbers, strings, arrays, objects and null
. Any
other type is omitted or transformed by JSON.stringify()
.
Functions
const invalidJson = { prop: () => {} }
JSON.stringify(invalidJson) // '{}'
Undefined
const invalidJson = { prop: undefined }
JSON.stringify(invalidJson) // '{}'
Symbol values
const invalidJson = { prop: Symbol() }
JSON.stringify(invalidJson) // '{}'
Symbol keys
const invalidJson = { [Symbol()]: true }
JSON.stringify(invalidJson) // '{}'
NaN and Infinity
const invalidJson = { one: Number.NaN, two: Number.POSITIVE_INFINITY }
JSON.stringify(invalidJson) // '{"one":null,"two":null}'
Classes
const invalidJson = { prop: new Set([]) }
JSON.stringify(invalidJson) // '{"prop":{}}'
Non-enumerable keys
const invalidJson = {}
Object.defineProperty(invalidJson, 'prop', { value: true, enumerable: false })
JSON.stringify(invalidJson) // '{}'
Array properties
const invalidJson = []
invalidJson.prop = true
JSON.stringify(invalidJson) // '[]'
Exceptions
JSON.stringify()
can throw on specific properties.
Cycles
const invalidJson = { prop: true }
invalidJson.self = invalidJson
JSON.stringify(invalidJson) // Throws: Converting circular structure to JSON
BigInt
const invalidJson = { prop: 0n }
JSON.stringify(invalidJson) // Throws: Do not know how to serialize a BigInt
Big properties
const invalidJson = { prop: '\n'.repeat(5e8) }
JSON.stringify(invalidJson) // Throws: Invalid string length
Infinite recursion
const invalidJson = { toJSON: () => ({ invalidJson }) }
JSON.stringify(invalidJson) // Throws: Maximum call stack size exceeded
Exceptions in toJSON()
const invalidJson = {
prop: {
toJSON: () => {
throw new Error('example')
},
},
}
JSON.stringify(invalidJson) // Throws: example
Exceptions in getters
const invalidJson = {
get prop() {
throw new Error('example')
},
}
JSON.stringify(invalidJson) // Throws: example
Exceptions in proxies
const invalidJson = new Proxy(
{ prop: true },
{
get: () => {
throw new Error('example')
},
},
)
JSON.stringify(invalidJson) // Throws: example
Related projects
safe-json-value
: ⛑️ JSON serialization should never failtruncate-json
: Truncate a JSON stringguess-json-indent
: Guess the indentation of a JSON string
Support
For any question, don't hesitate to submit an issue on GitHub.
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!