decode-json

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:

tries to extract a value from name field of the response and checks the value is a string
tries to extract a value from birth_year field of the response and checks the value is a string
tries to extract a value from height field of the response and parses the value as a float
tries to extract a value from mass field of the response and parses the value as a float
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?

`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'
// }

Name		Name	Last commit message	Last commit date
Latest commit History 12 Commits
.vscode		.vscode
scripts		scripts
src		src
tests		tests
.editorconfig		.editorconfig
.eslintignore		.eslintignore
.eslintrc.json		.eslintrc.json
.eslintrc.prod.json		.eslintrc.prod.json
.gitignore		.gitignore
.prettierignore		.prettierignore
.prettierrc.json		.prettierrc.json
.travis.yml		.travis.yml
LICENSE		LICENSE
README.md		README.md
ava.config.js		ava.config.js
package.json		package.json
rollup.config.js		rollup.config.js
tsconfig.dev.json		tsconfig.dev.json
tsconfig.json		tsconfig.json
tsconfig.prod.json		tsconfig.prod.json
yarn.lock		yarn.lock

License

owanturist/decode-json

Folders and files

Latest commit

History

Repository files navigation

decode-json

Installation

Example

API

DecodeResult

Decoder

Decoder.map

Decoder.chain

Decoder.decode

Decoder.decodeJson

Decode.string

Decode.boolean

Decode.int

Decode.float

Decode.unknown

Decode.exact

Decode.record

Decode.list

Decode.keyValue

Decode.record

Decode.tuple

Decode.oneOf

Decode.lazy

Decode.fail

Decode.succeed

Decode.field

Decode.index

Decode.optional

DecodeOptional.string

DecodeOptional.boolean

DecodeOptional.int

DecodeOptional.float

DecodeOptional.list

DecodeOptional.record

DecodeOptional.keyValue

DecodeOptional.field

DecodeOptional.index

RequiredDecodePath

OptionalDecodePath

DecodeError

EXPECT_STRING

EXPECT_BOOLEAN

EXPECT_FLOAT

EXPECT_INT

EXPECT_EXACT

EXPECT_ARRAY

EXPECT_OBJECT

FAILURE

REQUIRED_INDEX

REQUIRED_FIELD

AT_INDEX

IN_FIELD

OPTIONAL

ONE_OF

RUNTIME_EXCEPTION

DecodeJsonError

INVALID_JSON

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Languages

`DecodeResult`

`Decoder`

`Decoder.map`

`Decoder.chain`

`Decoder.decode`

`Decoder.decodeJson`

`Decode.string`

`Decode.boolean`

`Decode.int`

`Decode.float`

`Decode.unknown`

`Decode.exact`

`Decode.record`

`Decode.list`

`Decode.keyValue`

`Decode.record`

`Decode.tuple`

`Decode.oneOf`

`Decode.lazy`

`Decode.fail`

`Decode.succeed`

`Decode.field`

`Decode.index`

`Decode.optional`

`DecodeOptional.string`

`DecodeOptional.boolean`

`DecodeOptional.int`

`DecodeOptional.float`

`DecodeOptional.list`

`DecodeOptional.record`

`DecodeOptional.keyValue`

`DecodeOptional.field`

`DecodeOptional.index`

`RequiredDecodePath`

`OptionalDecodePath`

`DecodeError`

`EXPECT_STRING`

`EXPECT_BOOLEAN`

`EXPECT_FLOAT`

`EXPECT_INT`

`EXPECT_EXACT`

`EXPECT_ARRAY`

`EXPECT_OBJECT`

`FAILURE`

`REQUIRED_INDEX`

`REQUIRED_FIELD`

`AT_INDEX`

`IN_FIELD`

`OPTIONAL`

`ONE_OF`

`RUNTIME_EXCEPTION`

`DecodeJsonError`

`INVALID_JSON`

Packages