Nefarious Plastic Mannequins

    is-json-value
    TypeScript icon, indicating that this package has built-in type declarations

    1.6.0 • Public • Published

    Node Browsers TypeScript Codecov Minified size Mastodon Medium

    Check if a value is valid JSON.

    Features

    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 >=14.18.0 and browsers. It is an ES module and must be loaded using an import or import() statement, not require().

    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:

    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

    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!

    Install

    npm i is-json-value

    DownloadsWeekly Downloads

    85

    Version

    1.6.0

    License

    MIT

    Unpacked Size

    15 kB

    Total Files

    7

    Last publish

    Collaborators

    • ehmicky