Natural Polyglot Machine

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

    1.0.1 • Public • Published

    decode-json

    Coverage Status Minified + gzip Dependency count Known Vulnerabilities Types Total downloads

    The package you are about to use has been done under inspiration of Elm lang and elm/json package particularly.

    Using TypeScript is a great way to prevent some bugs during compile time but nothing can save us from runtime exceptions. Today "height" field coming from the GET /tallest-building endpoint is a number and you call .toFixed(2) to format it but next day it becomes a preformatted string and the app crashes with toFixed is not a function. The same thing could happen when an application uses localStorage and somebody changes a format to keep credentials token or last opened product information - value exists so you assume that it is valid but runtime error will make you unhappy very soon. Sounds familiar, doesn't?

    As a little attempt to workaround the issue we can try to protect our programs from unexpected data to come. To do so we should be able to explain what data we expect and how it should be transformed so an application can use it.

    Installation

    # with npm
    npm install decode-json --save
    
    # with yarn
    yarn install decode-json
    // with skypack
    import Decode, { Decoder } from 'https://cdn.skypack.dev/decode-json'
    import errorToHumanReadable from 'https://cdn.skypack.dev/decode-json/error-to-human-readable'
    
    // minifield version
    import Decode, { Decoder } from 'https://cdn.skypack.dev/decode-json?min'
    import errorToHumanReadable from 'https://cdn.skypack.dev/decode-json/error-to-human-readable?min'

    Example

    Let assume you are building a Star Wars fan wep application and you'd like to request Luke Skywalker's data from swapi.dev/api/people/1. You will get something like that:

    {
      "name": "Luke Skywalker",
      "birth_year": "19BBY",
      "height": "172",
      "mass": "77"
    }

    This is how it can be decoded safely:

    import Decode, { Decoder } from 'decode-json'
    
    const parseFloatDecoder: Decoder<number> = Decode.oneOf([
      Decode.float, // in case the value is float already
      Decode.string.chain(str => {
        const num = Number(str || '_') // prevents Number('') === 0
    
        if (isNaN(num)) {
          return Decode.fail(`Could not parse "${str}" as a float`)
        }
    
        return Decode.succeed(num)
      })
    ])
    
    const characterDecoder = Decode.shape({
      name: Decode.field('name').string,
      birthYear: Decode.field('birth_year').string,
      height: Decode.field('height').of(parseFloatDecoder),
      mass: Decode.field('mass').of(parseFloatDecoder)
    })
    
    const response = await fetch('https://swapi.dev/api/people/1')
    const data = await response.json()
    const characterResult = characterDecoder.decode(data)

    The decoder above does next steps:

    1. tries to extract a value from name field of the response and checks the value is a string
    2. tries to extract a value from birth_year field of the response and checks the value is a string
    3. tries to extract a value from height field of the response and parses the value as a float
    4. tries to extract a value from mass field of the response and parses the value as a float
    5. creates an output object with field name, birthYear, height and mass with values assigned respectively.

    If a response reflects our expectations so the results for swapi.dev/api/people/1 will look like:

    characterDecoder.decode(data)
    // == {
    //   value: {
    //     name: 'Luke Skywalker',
    //     birthYear: '19BBY',
    //     height: 172,
    //     mass: 77
    //   }
    // }

    But as soon as one of the 1-4 steps fails you will get a detailed report why it happened. Let's say the server sends birth height as a formatted string with a unit for some reason. Here is what you'll get when "172" string becomes "172 cm":

    characterDecoder.decode(data)
    // == {
    //   error: {
    //     type: 'IN_FIELD',
    //     field: 'height',
    //     error: {
    //       type: 'FAILURE',
    //       message: 'Could not parse "172 cm" as a float',
    //       source: '172 cm'
    //     }
    //   }
    // }

    And the trick is that by using a decoder a developer assumes that decode result might be either succeed or failed but not blindly trust that with 200 status code you'll get a valid data. So there is no way for the developer to ignore the awareness of failure but only handle the case somehow. Is not it an amazing concept?

    API

    DecodeResult

    This is what you always get as result of running both Decoder.decode and Decoder.decodeJson methods. It can be either { value: T } when a decoding has been successfully passed or { error: E } when any of decode, json parse or runtime error occur.

    import Decode, { Decoder, DecodeResult, DecodeError } from 'decode-json'
    
    const ageDecoder: Decoder<number> = Decode.field('age').int
    const badResult = ageDecoder.decode('oops')
    // == { error: { type: 'EXPECT_OBJECT', source: 'oops' } }
    const goodResult = ageDecoder.decode({ age: 27 }) // == { value: 27 }

    It's recommended to avoid destructuring assignment for DecodeResult because TypeScript won't help you with error handling:

    const { error, value } = ageDecoder.decode({ age: 27 })
    
    if (error) {
      showError(error)
    } else {
      showAge(value) // TS complains with "Object is possibly 'undefined'"
    }

    To workaround the issue just don't use destructuring assignment:

    const ageResult = ageDecoder.decode({ age: 27 })
    
    if (ageResult.error) {
      showError(ageResult.error)
    } else {
      showAge(ageResult.value) // no complains here
    }

    Decoder

    This is a declarative block of decode system which knows how to transform an expected data to a final result.

    import Decode, { Decoder } from 'decode-json'
    
    interface User {
      id: string
      nickname: string
      active: boolean
      age: number
    }
    
    const userDecoder: Decoder<User> = Decode.shape({
      id: Decode.field('uuid').string,
      nickname: Decode.field('username').string,
      active: Decode.field('is_active').boolean,
      age: Decode.field('age').int
    })

    Decoder.map

    Transforms decoded value. It can both keep the same type or change to another one:

    import Decode, { Decoder } from 'decode-json'
    
    const messageDecoder: Decoder<string> = Decode.string.map(message =>
      message.trim()
    )
    const charCountDecoder: Decoder<number> = Decode.string.map(
      message => message.trim().length
    )

    Decoder.chain

    Transforms decoded value decoder:

    import Decode, { Decoder } from 'decode-json'
    
    const displayDateDecoder: Decoder<string> = Decode.field(
      'active'
    ).boolean.chain(active => {
      return active
        ? Decode.field('last_activity').string
        : Decode.field('start_date').string
    })
    
    displayDateDecoder.decode({
      active: false,
      last_activity: '30 sec ago',
      start_date: '1 Sep 2020'
    }).value // == '1 Sep 2020'
    
    displayDateDecoder.decode({
      active: true,
      last_activity: '30 sec ago',
      start_date: '1 Sep 2020'
    }).value // == '30 sec ago'

    Decoder.decode

    Runs a decoder on unknown input data:

    import Decode from 'decode-json'
    
    Decode.boolean.decode('I am unknown input').error
    // == { type: 'EXPECT_BOOLEAN', source: 'I am unknown input' }
    
    Decode.boolean.decode(false).value // == false

    Decoder.decodeJson

    Runs a decoder on JSON string. Does the same as Decoder.decode but parses JSON first:

    import Decode from 'decode-json'
    
    Decode.string.decodeJson('I am just a string').error
    // == {
    //   type: 'INVALID_JSON',
    //   error: new SyntaxError('Unexpected token I in JSON at position 0'),
    //   source: 'I am just a string'
    // }
    
    const goodJson = Decode.string.decodeJson('"I am a JSON string"').value
    // == 'I am a JSON string'

    Decode.string

    Decodes a string value:

    import Decode from 'decode-json'
    
    Decode.string.decode(null).error // == { type: 'EXPECT_STRING', source: null }
    Decode.string.decode(true).error // == { type: 'EXPECT_STRING', source: true }
    Decode.string.decode(1234).error // == { type: 'EXPECT_STRING', source: 1234 }
    Decode.string.decode(12.3).error // == { type: 'EXPECT_STRING', source: 12.3 }
    Decode.string.decode('hi').value // == 'hi'

    Decode.boolean

    Decodes a boolean value:

    import Decode from 'decode-json'
    
    Decode.boolean.decode(null).error // == { type: 'EXPECT_BOOLEAN', source: null }
    Decode.boolean.decode(1234).error // == { type: 'EXPECT_BOOLEAN', source: 1234 }
    Decode.boolean.decode(12.3).error // == { type: 'EXPECT_BOOLEAN', source: 12.3 }
    Decode.boolean.decode('hi').error // == { type: 'EXPECT_BOOLEAN', source: 'hi' }
    Decode.boolean.decode(true).value // true

    Decode.int

    Decodes an integer value:

    import Decode from 'decode-json'
    
    Decode.int.decode(null).error // == { type: 'EXPECT_INT', source: null }
    Decode.int.decode(true).error // == { type: 'EXPECT_INT', source: true }
    Decode.int.decode('hi').error // == { type: 'EXPECT_INT', source: 'hi' }
    Decode.int.decode(12.3).error // == { type: 'EXPECT_INT', source: 12.3 }
    Decode.int.decode(1234).value // 1234

    Decode.float

    Decodes a float value:

    import Decode from 'decode-json'
    
    Decode.float.decode(null).error // == { type: 'EXPECT_FLOAT', source: null }
    Decode.float.decode(true).error // == { type: 'EXPECT_FLOAT', source: true }
    Decode.float.decode('hi').error // == { type: 'EXPECT_FLOAT', source: 'hi' }
    Decode.float.decode(12.3).value // 12.3
    Decode.float.decode(1234).value // 1234

    Decode.unknown

    Does not do anything with an incoming value, just bring it into TS as a unknown. This can be useful if you have particularly complex data that you would like to deal with later. Or if you are going to send it out a http request and do not care about its structure. Decoding of unknown never fails.

    import Decode from 'decode-json'
    
    Decode.unknown.decode(window.location).value // == window.location

    Decode.exact

    Decodes an exact primitive (either string, number, boolean or null) values.

    import Decode from 'decode-json'
    
    const pointDecoder = Decode.shape({
      type: Decode.field('type').exact('POINT'),
      x: Decode.field('axis_x').float,
      y: Decode.field('axis_y').float
    })
    
    pointDecoder.decode({
      type: 'LINE',
      x0: 1.2,
      y0: 3.4,
      x1: 5.6,
      x1: 7.8
    }).error
    // == {
    //   type: 'IN_FIELD',
    //   name: 'type',
    //   error: {
    //     type: 'EXPECT_EXACT',
    //     value: 'POINT',
    //     source: 'LINE'
    //   }
    // }

    Might be used with Decode.oneOf to build enum decoders:

    import Decode, { Decoder } from 'decode-json'
    
    enum Role {
      User,
      Manager,
      Admin
    }
    
    const roleDecoder: Decoder<Role> = Decode.oneOf([
      Decode.exact('USER', Role.User),
      Decode.exact('MANAGER', Role.Manager),
      Decode.exact('ADMIN', Role.Admin)
    ])

    Decode.record

    Decodes a key-value pairs as object:

    import Decode, { Decoder } from 'decode-json'
    
    const activeUsers: Decoder<Record<string, boolean>> = Decode.record(
      Decode.boolean
    )
    
    activeUsers.decode({
      John: false,
      Martin: false,
      Scott: true
    }).value // == { John: false, Martin: false, Scott: true }
    
    activeUsers.decode({
      John: false,
      Martin: false,
      Scott: 'yes'
    }).error
    // == {
    //   type: 'IN_FIELD',
    //   name: 'Scott',
    //   error: {
    //     type: 'EXPECT_BOOLEAN',
    //     source: 'yes'
    //   }
    // }

    Decode.list

    Decodes a list of values:

    import Decode, { Decoder } from 'decode-json'
    
    interface User {
      id: number
      username: string
    }
    
    const userDecoder: Decoder<User> = Decode.shape({
      id: Decode.field('id').int,
      username: Decode.field('user_name').string
    })
    
    Decode.list(userDecoder).decode([
      {
        id: 0,
        user_name: 'superstar'
      },
      {
        id: 1,
        user_name: 'boss'
      }
    ]).value // == [{ id: 0, username: 'superstar' }, { id: 1, username: 'boss' }]
    
    Decode.list(userDecoder).decode([
      {
        id: 0,
        user_name: 'lollypop'
      },
      {
        id: 1,
        name: 'boss'
      }
    ]).error
    // == {
    //   type: 'AT_INDEX',
    //   position: 1,
    //   error: {
    //     type: 'REQUIRED_FIELD',
    //     name: 'user_name',
    //     source: {
    //       id: 1,
    //       name: 'boss'
    //     }
    //   }
    // }

    Decode.keyValue

    Decodes key-value pairs as list of tuples:

    import Decode, { Decoder } from 'decode-json'
    
    const activeUsers: Decoder<Array<[string, boolean]>> = Decode.keyValue(
      Decode.boolean
    )
    
    activeUsers.decode({
      John: false,
      Martin: false,
      Scott: true
    }).value // == [[ 'John', false ], [ 'Martin', false ], [ 'Scott', true ]]
    
    activeUsers.decode({
      John: false,
      Martin: false,
      Scott: 'yes'
    }).error
    // == {
    //   type: 'IN_FIELD',
    //   name: 'Scott',
    //   error: {
    //     type: 'EXPECT_BOOLEAN',
    //     source: 'yes'
    //   }
    // }

    You also safely convert a key value from string to something else:

    import Decode, { Decoder } from 'decode-json'
    
    enum Currency {
      Rub,
      Eur,
      Usd
    }
    
    const currencyFromCode = (code: string): Currency => {
      switch (code) {
        case 'rub':
          return { value: Currency.Rub }
        case 'eur':
          return { value: Currency.Eur }
        case 'usd':
          return { value: Currency.Usd }
        default: {
          error: `Unknown currency code "${code}"`
        }
      }
    }
    
    const balance: Decoder<Array<[Currency, number]>> = Decode.keyValue(
      currencyFromCode,
      Decode.float
    )
    
    activeUsers.decode({
      rub: 42000.1,
      eur: 2400.87,
      usd: 13000.51
    }).value
    // == [
    //   [ Currency.Rub', 42000.1 ],
    //   [ Currency.Eur, 2400.87 ],
    //   [ Currency.Usd, 13000.51 ]
    // ]
    
    activeUsers.decode({
      rub: 42000.1,
      eur: 2400.87,
      usd: 13000.51,
      cny: 7912.08
    }).error
    // == {
    //   type: 'FAILURE',
    //   message: 'Unknown currency code "cny"'
    //   source: 'cny'
    // }

    Decode.record

    Combines decoded values to the corresponding object's fields:

    import Decode, { Decoder } from 'decode-json'
    
    interface User {
      id: string
      nickname: string
      active: boolean
      age: number
    }
    
    const userDecoder: Decoder<User> = Decode.shape({
      id: Decode.field('uuid').string,
      nickname: Decode.field('username').string,
      active: Decode.field('is_active').boolean,
      age: Decode.field('age').int
    })
    
    userDecoder.decode({
      uuid: 'user_12319238',
      username: 'wolverine',
      is_active: false,
      age: 61
    }).value
    // == {
    //   id: 'user_12319238',
    //   nickname: 'wolverine',
    //   active: false,
    //   age: 61
    // }
    
    userDecoder.decode({
      uuid: 'user_12319238',
      username: 'wolverine',
      is_active: 'yes',
      age: 61
    }).error
    // == {
    //   type: 'IN_FIELD',
    //   field: 'is_active',
    //   error: {
    //     type: 'EXPECT_BOOLEAN',
    //     source: 'yes'
    //   }
    // }

    Note: Decode.record does not decode any value! It only combines another decoders' values.

    You also notice that shape's fields does describe any path fragments for assigned decoders - these are only destinations of decoded values.

    Decode.tuple

    Combines decoded values to the corresponding tuple segments:

    import Decode, { Decoder } from 'decode-json'
    
    const pointDecoder: Decoder<[number, number]> = Decode.tuple(
      Decode.field('x').float,
      Decode.field('y').float
    )
    
    pointDecoder.decode({
      x: 12.34,
      y: 56.78
    }).value // == [ 12.34, 56.78 ]
    
    pointDecoder.decode({
      x: 12.34,
      y: '56.78'
    }).error
    // == {
    //   type: 'IN_FIELD',
    //   field: 'y',
    //   error: {
    //     type: 'EXPECT_FLOAT',
    //     source: '56.78'
    //   }
    // }

    Note: Decode.tuple does not decode any value! It only combines another decoders' values.

    You also notice that tuple's segments does describe any path fragments for assigned decoders - these are only destinations of decoded values.

    Decode.oneOf

    Try a bunch of different decoders. This can be useful if the values may come in a couple different formats.

    import Decode, { Decoder } from 'decode-json'
    
    const dateDecoder: Decoder<Date> = Decode.oneOf([
      Decode.int.map(timestamp => new Date(timestamp)),
      Decode.string.chain(datetime => {
        const date = new Date(datetime)
    
        if (isNaN(date.getMilliseconds())) {
          return Decode.fail(`Could not create a date from "${datetime}"`)
        }
    
        return Decode.succeed(date)
      })
    ])
    
    dateDecoder.decode(1609542413856).value // == new Date('Fri, 01 Jan 2021 23:06:53 GMT')
    dateDecoder.decode('Fri, 01 Jan 2021 23:06:53 GMT').value // == new Date(1609542413856)
    dateDecoder.decode('01|01|2021').error
    // == {
    //   type: 'ONE_OF',
    //   errors: [
    //     {
    //       type: 'EXPECT_INT',
    //       source: '01|01|2021'
    //     },
    //     {
    //       type: 'FAILURE',
    //       message: 'Could not create a date from "01|01|2021"',
    //       source: '01|01|2021'
    //     }
    //   ]
    // }

    This is a powerful tool to work with inconsistent data:

    import Decode, { Decoder } from 'decode-json'
    
    interface User {
      id: string
      nickname: string
      active: boolean
      age: number
    }
    
    const userDecoder: Decoder<User> = Decode.oneOf([
      // legacy version
      Decode.shape({
        id: Decode.field('index').int.map(String),
        nickname: Decode.field('name').string,
        active: Decode.field('is_active').boolean,
        age: Decode.field('years').int
      }),
    
      // latest version
      Decode.shape({
        id: Decode.field('uuid').string,
        nickname: Decode.field('username').string,
        active: Decode.field('isActive').boolean,
        age: Decode.field('age').int
      })
    ])
    
    userDecoder.decode({
      index: 0,
      name: 'Rachel',
      is_active: true,
      years: 30
    }).value
    // == {
    //   id: '0',
    //   nickname: 'Rachel',
    //   active: true,
    //   age: 30
    // }
    
    userDecoder.decode({
      uuid: 'uuid-id-is-here',
      username: 'Ross',
      isActive: true,
      age: 32
    }).value
    // == {
    //   id: 'uuid-id-is-here',
    //   nickname: 'Ross',
    //   active: true,
    //   age: 32
    // }

    It also can be used to set a default value if all of the decoders fails for whatever reason:

    import Decode from 'decode-json'
    
    const configDecoder = Decode.oneOf([
      Decode.shape({
        hostUrl: Decode.field('HOST_URL').string,
        apiVersion: Decode.field('API_VERSION').int
      }),
    
      Decode.succeed({
        hostUrl: 'localhost:8000',
        apiVersion: 1
      })
    ])
    
    configDecoder.decode(null).value
    // == {
    //   hostUrl: 'localhost:8000',
    //   apiVersion: 1
    // }

    Decode.lazy

    Sometimes you have a recursive data structures, like comments with responses, which also are comments with responses, which also... you got the point. To make sure a decoder unrolls lazily it should use Decode.lazy wrapper:

    import Decode, { Decoder } from 'decode-json'
    
    interface Comment {
      message: string
      responses: Array<Comment>
    }
    
    const commentDecoder: Decoder<Comment> = Decode.shape({
      message: Decode.field('mes').string,
      responses: Decode.field('res').list(Decode.lazy(() => commentDecoder))
    })
    
    commentDecoder.decode({
      mes: 'oops',
      res: [
        {
          mes: 'yes',
          res: [
            {
              mes: 'here we go again',
              res: []
            }
          ]
        },
        {
          mes: 'no',
          res: [
            {
              mes: 'that is right',
              res: [
                {
                  mes: 'agree',
                  res: []
                }
              ]
            }
          ]
        }
      ]
    }).value
    // == {
    //   message: 'oops',
    //   responses: [
    //     {
    //       message: 'yes',
    //       responses: [
    //         {
    //           message: 'here we go again',
    //           responses: []
    //         }
    //       ]
    //     },
    //     {
    //       message: 'no',
    //       responses: [
    //         {
    //           message: 'that is right',
    //           responses: [
    //             {
    //               message: 'agree',
    //               responses: []
    //             }
    //           ]
    //         }
    //       ]
    //     }
    //   ]
    // }

    Decode.fail

    Ignores a decoding value and make the decoder fail. This is handy when used with Decode.oneOf or Decoder.chain where you want to give a custom error message in some cases.

    import Decode, { Decoder } from 'decode-json'
    
    const positiveIntDecoder: Decoder<number> = Decode.int.chain(int => {
      if (int > 0) {
        return Decode.succeed(int)
      }
    
      return Decode.fail(`Expects positive int but get ${int} instead`)
    })
    
    positiveIntDecoder.decode(42).value // == 42
    
    positiveIntDecoder.decode(-1).error
    // == {
    //   type: 'FAILURE',
    //   message: 'Expects positive int but get -1 instead',
    //   source: -1
    // }

    Note: see Decode.oneOf and Decoder.chain for more examples.

    Decode.succeed

    Ignores a decoding value and produce a certain value. Handy when used with Decode.oneOf or Decoder.chain.

    import Decode, { Decoder } from 'decode-json'
    
    const messageDecoder: Decoder<string> = Decode.string.chain(message => {
      if (message.length >= 10) {
        return Decode.succeed(message)
      }
    
      return Decode.fail(
        `An input message is only ${message.length} chars long but at least 10 is required`
      )
    })
    
    messageDecoder.decode('Quite long message').value // == 'Quite long message'
    messageDecoder.decode('Short').error
    // == An input message is only 5 chars long but at least 10 is required
    messageDecoder.decode(123).error // == { type: 'EXPECT_STRING', source: 123 }

    Can be used to define hardcoded values.

    import Decode, { Decoder } from 'decode-json'
    
    const pointDecoder = Decoder.shape({
      x: Decode.index(0).float,
      y: Decode.index(1).float,
      z: Decode.succeed(0)
    })
    
    pointDecoder.decode([0.31, 8.17]).value // == { x: 0.31, y: 8.17, z: 0 }

    Note: see Decode.oneOf and Decoder.chain for more examples.

    Decode.field

    Creates a RequiredDecodePath instance.

    import Decode, { RequiredDecodePath } from 'decode-json'
    
    const currentUserPath: RequiredDecodePath = Decode.field('current_user')

    Decode.index

    Creates a RequiredDecodePath instance.

    import Decode, { RequiredDecodePath } from 'decode-json'
    
    const secondPointPath: RequiredDecodePath = Decode.index(1)

    Decode.optional

    Creates DecodeOptional instance.

    DecodeOptional.string

    Behaves exactly as Decode.string but decodes null and undefined as null:

    import Decode from 'decode-json'
    
    Decode.optional.string.decode(1234).error
    // == {
    //   type: 'OPTIONAL',
    //   error: { type: 'EXPECT_STRING', source: 1234 }
    // }
    Decode.optional.string.decode(null).value // == null
    Decode.optional.string.decode(undefined).value // == null
    Decode.optional.string.decode('hi').value // == 'hi'

    DecodeOptional.boolean

    Behaves exactly as Decode.boolean but decodes null and undefined as null:

    import Decode from 'decode-json'
    
    Decode.optional.boolean.decode(1234).error
    // == {
    //   type: 'OPTIONAL',
    //   error: { type: 'EXPECT_BOOLEAN', source: 1234 }
    // }
    Decode.optional.boolean.decode(null).value // == null
    Decode.optional.boolean.decode(undefined).value // == null
    Decode.optional.boolean.decode(true).value // == true

    DecodeOptional.int

    Behaves exactly as Decode.int but decodes null and undefined as null:

    import Decode from 'decode-json'
    
    Decode.optional.int.decode(12.3).error
    // == {
    //   type: 'OPTIONAL',
    //   error: { type: 'EXPECT_INT', source: 12.3 }
    // }
    Decode.optional.int.decode(null).value // == null
    Decode.optional.int.decode(undefined).value // == null
    Decode.optional.int.decode(1234).value // == 1234

    DecodeOptional.float

    Behaves exactly as Decode.float but decodes null and undefined as null:

    import Decode from 'decode-json'
    
    Decode.optional.float.decode(false).error
    // == {
    //   type: 'OPTIONAL',
    //   error: { type: 'EXPECT_FLOAT', source: false }
    // }
    Decode.optional.float.decode(null).value // == null
    Decode.optional.float.decode(undefined).value // == null
    Decode.optional.float.decode(12.3).value // == 12.3

    DecodeOptional.list

    Behaves exactly as Decode.list but decodes null and undefined as null:

    import Decode, { Decoder } from 'decode-json'
    
    const idsDecoder: Decoder<null | Array<number>> = Decode.optional.list(
      Decode.int
    )
    
    idsDecoder.decode(null).value // == null
    idsDecoder.decode(undefined).value // == null
    idsDecoder.decode([0, 2, 3]).value // == [ 0, 2, 3 ]

    Note that optional statement here is assigned to list decoder, but not to it's items, so this one will fail:

    idsDecoder.decode([ 0, null, 2, 3 ]).error
    {
      type: 'OPTIONAL',
      error: {
        type: 'AT_INDEX',
        position: 1,
        error: { type: 'EXPECT_INT', source: null }
      }
    }

    If you expect both array and the items to be optional you can do it like that:

    import Decode, { Decoder } from 'decode-json'
    
    const idsDecoder: Decoder<null | Array<null | number>> = Decode.optional.list(
      Decode.optional.int
    )
    
    idsDecoder.decode(null).value // === null
    idsDecoder.decode([0, null, 2, 3]).value // === [ 0, null, 2, 3 ]

    DecodeOptional.record

    Behaves exactly as Decode.record but decodes null and undefined as null:

    import Decode, { Decoder } from 'decode-json'
    
    const blackListDecoder: Decoder<null | Record<
      string,
      boolean
    >> = Decode.optional.record(Decode.boolean)
    
    blackListDecoder.decode(null).value // == null
    blackListDecoder.decode(undefined).value // == null
    blackListDecoder.decode({
      John: false,
      Emma: true,
      Tom: true
    }).value
    // == {
    //   John: false,
    //   Emma: true,
    //   Tom: true
    // }

    Note that optional statement here is assigned to record decoder, but not it's items, so this one will fail:

    blackListDecoder.decode({
      John: false,
      Emma: true,
      Tom: true,
      Adam: null
    }).error
    // == {
    //   type: 'OPTIONAL',
    //   error: {
    //     type: 'IN_FIELD',
    //     name: 'Adam',
    //     error: { type: 'EXPECT_BOOLEAN', source: null }
    //   }
    // }

    If you expect both object and the items to be optional you can do it like that:

    import Decode, { Decoder } from 'decode-json'
    
    const blackListDecoder: Decoder<null | Record<
      string,
      null | boolean
    >> = Decode.optional.record(Decode.boolean)
    
    blackListDecoder.decode(null).value // === null
    blackListDecoder.decode({
      John: false,
      Emma: true,
      Tom: true,
      Adam: null
    }).value
    // == {
    //   John: false,
    //   Emma: true,
    //   Tom: true,
    //   Adam: null
    // }

    DecodeOptional.keyValue

    Behaves exactly as Decode.keyValue but decodes null and undefined as null:

    import Decode, { Decoder } from 'decode-json'
    
    const blackListDecoder: Decoder<null | Array<
      [string, boolean]
    >> = Decode.optional.keyValue(Decode.boolean)
    
    blackListDecoder.decode(null).value // == null
    blackListDecoder.decode(undefined).value // == null
    blackListDecoder.decode({
      John: false,
      Emma: true,
      Tom: true
    }).value
    // == [
    //   [ 'John', false ],
    //   [ 'Emma', true ],
    //   [ 'Tom', true ]
    // ]

    Note that optional statement here is assigned to keyValue decoder, but not to it's items, so this one will fail:

    blackListDecoder.decode({
      John: false,
      Emma: true,
      Tom: true,
      Adam: null
    }).error
    // == {
    //   type: 'OPTIONAL',
    //   error: {
    //     type: 'IN_FIELD',
    //     name: 'Adam',
    //     error: { type: 'EXPECT_BOOLEAN', source: null }
    //   }
    // }

    If you expect both object and the items to be optional you can do it like that:

    import Decode, { Decoder } from 'decode-json'
    
    const blackListDecoder: Decoder<null | Array<
      [string, null | boolean]
    >> = Decode.optional.keyValue(Decode.optional.boolean)
    
    blackListDecoder.decode(null).value // === null
    blackListDecoder.decode({
      John: false,
      Emma: true,
      Tom: true,
      Adam: null
    }).value
    // == [
    //   [ 'John', false ],
    //   [ 'Emma', true ],
    //   [ 'Tom', true ],
    //   [ 'Adam', null ]
    // ]

    DecodeOptional.field

    Creates an OptionalDecodePath instance.

    import Decode, { OptionalDecodePath } from 'decode-json'
    
    const nameFieldDecoder: OptionalDecodePath = Decode.optional.field('name')

    DecodeOptional.index

    Creates an OptionalDecodePath instance.

    import Decode, { OptionalDecodePath } from 'decode-json'
    
    const headDecoder: OptionalDecodePath = Decode.optional.index(0)

    RequiredDecodePath

    It provides an API to build decoders for some specific path described with Decoder.field and Decoder.index:

    import Decode from 'decode-json'
    
    const pointDecoder = Decode.tuple(
      Decode.field('x').float,
      Decode.field('y').float
    )
    
    Decode.field('center').of(pointDecoder).decode([1, 2, 3]).error
    // == {
    //   type: 'EXPECT_OBJECT',
    //   source: [ 1, 2, 3 ]
    // }
    
    Decode.field('center').of(pointDecoder).decode({ name: 'John' }).error
    // == {
    //   type: 'REQUIRED_FIELD',
    //   name: 'center',
    //   source: { name: 'John' }
    // }
    
    Decode.field('center')
      .of(pointDecoder)
      .decode({
        center: { x: 1.2 }
      }).error
    // == {
    //   type: 'IN_FIELD',
    //   name: 'center',
    //   error: {
    //     type: 'REQUIRED_FIELD',
    //     name: 'y',
    //     source: { x: 1.2 }
    //   }
    // }
    
    Decode.field('center')
      .of(pointDecoder)
      .decode({
        center: { x: 1.2, y: 3.4 }
      }).value // == [ 1.2, 3.4 ]

    The same idea works for RequiredDecodePath.index:

    import Decode from 'decode-json'
    
    Decode.index(0).int.decode({}).error
    // == {
    //   type: 'EXPECT_ARRAY',
    //   source: {}
    // }
    
    Decode.index(0).int.decode([]).error
    // == {
    //   type: 'REQUIRED_INDEX',
    //   position: 0,
    //   source: []
    // }
    
    Decode.index(0).int.decode([null]).error
    // == {
    //   type: 'AT_INDEX',
    //   position: 0,
    //   error: { type: 'EXPECT_INT', source: null }
    // }
    
    Decode.index(0).int.decode([42]).value // == 42

    OptionalDecodePath

    It provides an API to build decoders for some specific path described with DecodeOptional.field and DecodeOptional.index:

    import Decode from 'decode-json'
    
    const pointDecoder = Decode.tuple(
      Decode.field('x').float,
      Decode.field('y').float
    )
    
    Decode.optional
      .field('center')
      .of(pointDecoder)
      .decode({
        center: { x: 1.2 }
      }).error
    // == {
    //   type: 'OPTIONAL',
    //   error: {
    //     type: 'IN_FIELD',
    //     name: 'center',
    //     error: {
    //       type: 'REQUIRED_FIELD',
    //       name: 'y',
    //       source: { x: 1.2 }
    //     }
    //   }
    // }
    
    Decode.optional
      .field('center')
      .of(pointDecoder)
      .decode({
        center: { x: 1.2, y: 3.4 }
      }).value // == [ 1.2, 3.4 ]

    Note that optional statement here is assigned to .field or .index, so this one will fail:

    import Decode from 'decode-json'
    
    Decode.optional.field('name').string.decode({ name: null }).error
    {
      type: 'OPTIONAL',
      error: {
        type: 'IN_FIELD',
        name: 'name',
        error: { type: 'EXPECT_STRING', source: null }
      }
    }

    But won't for this inputs:

    import Decode from 'decode-json'
    
    Decode.optional.field('name').string.decode(null).value // == null
    Decode.optional.field('name').string.decode({}).value // == null
    Decode.optional.field('name').string.decode({ name: 'Peter' }).value // == 'Peter'

    Another words are OptionalDecodePath.field expects that object with field is optional, but not a value of the field. If you expect the value is optional too you do:

    import Decode from 'decode-json'
    
    Decode.optional.field('name').optional.string.decode({ name: null }).value // == null

    The same idea works for OptionalDecodePath.index:

    import Decode from 'decode-json'
    
    Decode.optional.index(0).int.decode(null).value // == null
    Decode.optional.index(0).int.decode([]).value // == null
    Decode.optional.index(0).int.decode([42]).value // == 42
    Decode.optional.index(0).int.decode([null]).error
    // == {
    //   type: 'OPTIONAL',
    //   error: {
    //     type: 'AT_INDEX',
    //     position: 0,
    //     error: { type: 'EXPECT_INT', source: null }
    //   }
    // }
    
    Decode.optional.index(0).optional.int.decode([null]).value // == null

    DecodeError

    A set of errors describe what went wrong during decoding of unknown value with Decoder.decode. The error consist of plain JavaScript data types such as strings, numbers, objects and arrays so it can be stringified to JSON without any information losses. It might be helpful for sending to tracking tools as part of report or to display friendly message in UI with error-to-human-readable.ts. You can always build your own functions for error formatting.

    EXPECT_STRING

    Signature:

    // not exported
    type ExpectStringError = {
      type: 'EXPECT_STRING'
      source: unknown
    }

    Occurs when source fails a check to be a string:

    import Decode from 'decode-json'
    
    Decode.string.decode(123).error
    // == {
    //   type: 'EXPECT_STRING',
    //   source: 123
    // }

    EXPECT_BOOLEAN

    Signature:

    // not exported
    type ExpectBooleanError = {
      type: 'EXPECT_BOOLEAN'
      source: unknown
    }

    Occurs when source fails a check to be a boolean value:

    import Decode from 'decode-json'
    
    Decode.string.decode('I am a string').error
    // == {
    //   type: 'EXPECT_BOOLEAN',
    //   source: 'I am a string'
    // }

    EXPECT_FLOAT

    Signature:

    // not exported
    type ExpectFloatError = {
      type: 'EXPECT_FLOAT'
      source: unknown
    }

    Occurs when source fails a check to be a float number:

    import Decode from 'decode-json'
    
    Decode.int.decode(false).error
    // == {
    //   type: 'EXPECT_FLOAT',
    //   source: false
    // }

    EXPECT_INT

    Signature:

    // not exported
    type ExpectIntError = {
      type: 'EXPECT_INT'
      source: unknown
    }

    Occurs when source fails a check to be an integer number:

    import Decode from 'decode-json'
    
    Decode.int.decode(12.3).error
    // == {
    //   type: 'EXPECT_INT',
    //   source: 12.3
    // }

    EXPECT_EXACT

    Signature:

    // not exported
    type ExpectExactError = {
      type: 'EXPECT_EXACT'
      value: string | number | boolean | null
      source: unknown
    }

    Occurs when source is not equal to value:

    import Decode from 'decode-json'
    
    Decode.exact('ADMIN').decode('admin').error
    // == {
    //   type: 'EXPECT_EXACT',
    //   value: 'ADMIN',
    //   source: 'admin'
    // }
    
    const theWorstYear = new Date(2020, 0, 1)
    
    Decode.exact(2020, theWorstYear).decode(2021).error
    // == {
    //   type: 'EXPECT_EXACT',
    //   value: 2020,
    //   source: 2021
    // }

    EXPECT_ARRAY

    Signature:

    // not exported
    type ExpectArrayError = {
      type: 'EXPECT_ARRAY'
      source: unknown
    }

    Occurs when source fails a check to be an array:

    import Decode from 'decode-json'
    
    Decode.list(Decode.int).decode({ title: 'NY times' }).error
    // == {
    //   type: 'EXPECT_ARRAY',
    //   source: { title: 'NY times' }
    // }
    
    Decode.index(2).boolean.decode({ name: 'Boris' }).error
    // == {
    //   type: 'EXPECT_ARRAY',
    //   source: { name: 'Boris' }
    // }

    EXPECT_OBJECT

    Signature:

    // not exported
    type ExpectObjectError = {
      type: 'EXPECT_OBJECT'
      source: unknown
    }

    Occurs when source fails a check to be an object:

    import Decode from 'decode-json'
    
    Decode.record(Decode.int).decode([1, 2, 3]).error
    // == {
    //   type: 'EXPECT_OBJECT',
    //   source: [ 1, 2, 3 ]
    // }
    
    Decode.keyValue(Decode.string).decode(`Let's rock!`).error
    // == {
    //   type: 'EXPECT_OBJECT',
    //   source: 'Let\'s rock!'
    // }
    
    Decode.field('length').boolean.decode([true, false]).error
    // == {
    //   type: 'EXPECT_OBJECT',
    //   source: [ true, false ]
    // }

    FAILURE

    Signature:

    // not exported
    type FailureError = {
      type: 'FAILURE'
      message: string
      source: unknown
    }

    Occurs either when Decode.fail run into decoding or when key converting in Decode.keyValue (or DecodeOptional.keyValue) fails.

    import Decode from 'decode-json'
    
    Decode.int
      .chain(num => {
        if (num > 0) {
          return Decode.succeed(num)
        }
    
        return Decode.fail('Expect positive integer')
      })
      .decode(-1).error
    // == {
    //   type: 'FAILURE',
    //   message: 'Expect positive integer',
    //   source: -1
    // }
    
    Decode.keyValue(key => {
      const num = parseInt(key, 10)
    
      if (!isNaN(num)) {
        return Decode.succeed(num)
      }
    
      return Decode.fail('Could not convert string to integer')
    }, Decode.string).decode({
      1: 'first',
      2: 'second',
      _3: 'third'
    })
    // == {
    //   type: 'FAILURE',
    //   message: 'Could not convert string to integer',
    //   source: '_3'
    // }

    REQUIRED_INDEX

    Signature:

    // not exported
    type RequiredIndexError = {
      type: 'REQUIRED_INDEX'
      position: number
      source: Array<unknown>
    }

    Occurs when Decode.index could not reach an element at a required position of a source array.

    import Decode from 'decode-json'
    
    Decode.index(2).boolean.decode([true, false]).error
    // == {
    //   type: 'REQUIRED_INDEX',
    //   position: 2,
    //   source: [ true, false ]
    // }

    REQUIRED_FIELD

    Signature:

    // not exported
    type RequiredFieldError = {
      type: 'REQUIRED_FIELD'
      name: string
      source: Record<string, unknown>
    }

    Occurs when Decode.field could not reach a field by name in a source object.

    import Decode from 'decode-json'
    
    Decode.field('age').int.decode({
      id: 123,
      name: 'Tom'
    }).error
    // == {
    //   type: 'REQUIRED_FIELD',
    //   name: 'age',
    //   source: { id: 123, name: 'Tom' }
    // }

    AT_INDEX

    Signature:

    // not exported
    type AtIndexError = {
      type: 'AT_INDEX'
      position: number
      error: DecodeError
    }

    Occurs when a decoding fails with an error at some specific array's element at position:

    import Decode from 'decode-json'
    
    Decode.list(Decode.int).decode([1, 2, 2.5]).error
    // == {
    //   type: 'AT_INDEX',
    //   position: 2,
    //   error: {
    //     type: 'EXPECT_INT',
    //     source: 2.5
    //   }
    // }
    
    Decode.index(2).boolean.decode([false, true, 'ok']).error
    // == {
    //   type: 'AT_INDEX',
    //   position: 2,
    //   error: {
    //     type: 'EXPECT_BOOLEAN',
    //     source: 'ok'
    //   }
    // }

    IN_FIELD

    Signature:

    // not exported
    type InFieldError = {
      type: 'IN_FIELD'
      name: string
      error: DecodeError
    }

    Occurs when a decoding fails with an error in some specific object's field with name:

    import Decode from 'decode-json'
    
    Decode.record(Decode.int).decode({
      one: 1,
      two: 2,
      three: '3rd'
    }).error
    // == {
    //   type: 'IN_FIELD',
    //   name: 'three',
    //   error: {
    //     type: 'EXPECT_INT',
    //     source: '3rd'
    //   }
    // }
    
    Decode.keyValue(Decode.string).decode({
      Russia: 'Moscow',
      Netherlands: 'Amsterdam',
      USA: null
    }).error
    // == {
    //   type: 'IN_FIELD',
    //   name: 'USA',
    //   error: {
    //     type: 'EXPECT_STRING',
    //     source: null
    //   }
    // }
    
    Decode.field('is_active').boolean.decode({
      id: 123,
      name: 'Carl',
      is_active: 'no'
    }).error
    // == {
    //   type: 'IN_FIELD',
    //   name: 'is_active',
    //   error: {
    //     type: 'EXPECT_BOOLEAN',
    //     source: 'no'
    //   }
    // }

    OPTIONAL

    Signature:

    // not exported
    type OptionalDecodeError = {
      type: 'OPTIONAL'
      error: DecodeError
    }

    Indicates that an error occurs for an optional path or value:

    import Decode from 'decode-json'
    
    Decode.optional.int.decode(1.23).error
    // == {
    //   type: 'OPTIONAL',
    //   error: {
    //     type: 'EXPECT_INT',
    //     source: 1.23
    //   }
    // }
    
    Decode.optional.field('lat').float.decode({
      lng: 123.45,
      lat: null
    }).error
    // == {
    //   type: 'OPTIONAL',
    //   error: {
    //     type: 'IN_FIELD',
    //     name: 'lat',
    //     error: {
    //       type: 'EXPECT_FLOAT',
    //       source: null
    //     }
    //   }
    // }

    ONE_OF

    Signature:

    // not exported
    type OneOfError = {
      type: 'ONE_OF'
      errors: Array<DecodeError>
    }

    Occurs when none of Decode.oneOf decoders passes with errors from each of the decoders:

    import Decode from 'decode-json'
    
    Decode.oneOf([
      Decode.tuple(
        // for coordinates as object
        Decode.field('lat').float,
        Decode.field('lng').float
      ),
    
      Decode.tuple(
        // for coordinates as array
        Decode.index(0).float,
        Decode.index(1).float
      )
    ]).decode({ lat: 1.23, lon: 4.56 }).error
    // == {
    //   type: 'ONE_OF',
    //   errors: [
    //     {
    //       type: 'REQUIRED_FIELD',
    //       name: 'lng',
    //       source: { lat: 1.23, lon: 4.56 }
    //     },
    //     {
    //       type: 'EXPECT_ARRAY',
    //       source: { lat: 1.23, lon: 4.56 }
    //     }
    //   ]
    // }

    RUNTIME_EXCEPTION

    Signature:

    type RuntimeException = {
      type: 'RUNTIME_EXCEPTION'
      error: Error
    }

    Occurs when something unexpected happens while decoding is running so you should never worry about wrapping a decoder to try..catch because it does it for you automatically in runtime and TypeScript take care about correct usage during compile time.

    DecodeJsonError

    A set of errors describe what went wrong during decoding of JSON string with Decoder.decodeJson. The set is a union of DecodeError with one more specific error for parse json exception.

    INVALID_JSON

    Signature:

    type RuntimeException = {
      type: 'INVALID_JSON'
      error: SyntaxError
      source: string
    }

    Occurs when Decoder.decodeJson tries to decode invalid JSON string:

    import Decode from 'decode-json'
    
    Decode.string.decodeJson('I am just a string').error
    // == {
    //   type: 'INVALID_JSON',
    //   error: new SyntaxError('Unexpected token I in JSON at position 0'),
    //   source: 'I am just a string'
    // }

    Install

    npm i decode-json

    DownloadsWeekly Downloads

    361

    Version

    1.0.1

    License

    BSD-3-Clause

    Unpacked Size

    350 kB

    Total Files

    66

    Last publish

    Collaborators

    • owanturist