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:

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
• Decoder
  • Decoder.map
  • Decoder.chain
  • Decoder.decode
  • Decoder.decodeJson
• Decode
  • 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
  • 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

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