purescript-json-codecs

A bidirectional and unidirectional value-based and runtime-configurable typeclass-based JSON codec library. Essentially, argonaut-codec and codec-argonaut in one library with clear imports, flexible error types, error accumulation, and better performance (claim unproven but hopefully true).

Design

See DESIGN.md for the reasoning behind this library's design. The rest of this section covers my goals and where I'm at in that process.

Address gripes with other JSON codec libraries:

simple-json:
- I don't want to have to fork or copy the repo to benefit from it / change various type class instances.
- I don't want to use your information-poor error type, NonEmptyList ForeignError
argonaut-codec/codec-argonaut:
- I don't want to use your information-poor error type, JsonDecodeError
- I want one library for value-based or typeclass-based codecs

Improve error messages:

show me all failures, not just the first one (i.e. use V, not Either)
show me hints separate from the error message
on type mismatch errors, show me what you expected AND got, not just what was expected
give me more control over what my error type is

Provide a single library for both versions of codecs and both directions of codecs

Provide record syntax I enjoy using

See examples below

Error Messages for `test/Main.purs`

`PrimitiveJsonError`:

Decode Int to Int:
1

Decode Int to String:
while decoding the type, Int
  at path: ROOT
Expected number but got string: "foo"
  at path: ROOT

Decode Record to Int:
while decoding the type, Int
  at path: ROOT
Expected number but got object with 7 keys
  at path: ROOT

Decode Record incorrectly:
while decoding the type, Record
  at path: ROOT
  Expected object but got array of length 10
    at path: ROOT.array
  Expected string but got boolean: true
    at path: ROOT.boolean
  Expected string but got number: 9.0
    at path: ROOT.int
  Expected boolean but got number: 1.4
    at path: ROOT.number
  while decoding the type, Int
    at path: ROOT.object
  Expected number but got object with 4 keys
    at path: ROOT.object
  Expected array but got object with 2 keys
    at path: ROOT.record
  Expected number but got string: "hello"
    at path: ROOT.string

`Doc Void`

Decode Int to Int:
1

Decode Int to String:
while decoding the type, Int
  at path: ROOT
  Expected number but got string: "foo"
    at path: ROOT

Decode Record to Int:
while decoding the type, Int
  at path: ROOT
  Expected number but got object with 7 keys
    at path: ROOT

Decode Record incorrectly:
while decoding the type, Record
  at path: ROOT
  Expected object but got array of length 10
    at path: ROOT.array

  Expected string but got boolean: true
    at path: ROOT.boolean

  Expected string but got number: 9.0
    at path: ROOT.int

  Expected boolean but got number: 1.4
    at path: ROOT.number

  while decoding the type, Int
    at path: ROOT.object
    Expected number but got object with 4 keys
      at path: ROOT.object

  Expected array but got object with 2 keys
    at path: ROOT.record

  Expected number but got string: "hello"
    at path: ROOT.string

`Doc GraphicsParam`

Same as Doc Void but with colors:

Codec Examples

Value-based codec where all fields are required

-- Error messages are outputted with color.
fooDecoder :: JsonDecoder (Doc GraphicsParam) _
fooDecoder =
  decodeRecord
    { a: ade $ decodeRecord
        { foo: ade $ decodeBoolean }
    , b: ade $ decodeEither decodeInt $ decodeArray decodeString
    , c: ade $ decodeMaybeTagged decodeString
    }

fooEncoder :: _ -> Json
fooEncoder =
  encodeRecord
    { a: ade $ encodeRecord
        { foo: ade $ encodeBoolean }
    , b: ade $ encodeEither encodeInt $ encodeArray encodeString
    , c: ade $ encodeMaybeTagged encodeString
    }

Value-based codec where some fields are optional

{-
This decodes to
  { a :: { foo :: Boolean }
  , b :: Either Int (Array String)
  , c :: Maybe String
  , optionalA :: Maybe Int    -- decodes to Nothing if field is missing.
  , optionalB :: Maybe String -- decodes to Nothing if field is missing.
  }
-}
barDecoder :: JsonDecoder (Doc GraphicsParam) _
barDecoder =
  decodeRecord' $ buildRecordDecoder $
    decodeRequiredProps
      { a: ade $ decodeRecord
          { foo: ade $ decodeBoolean }
      , b: ade $ decodeEither decodeInt $ decodeArray decodeString
      , c: ade $ decodeMaybeTagged decodeString
      }
    >>> decodeOptionalProps
      { optionalA: ade decodeInt
      , optionalB: ade decodeString
      }

barEncoder :: Jsonencoder (Doc GraphicsParam) _
barEncoder =
  encodeRecord' $ buildRecordencoder $
    encodeRequiredProps
      { a: ade $ encodeRecord
          { foo: ade $ encodeBoolean }
      , b: ade $ encodeEither encodeInt $ encodeArray encodeString
      , c: ade $ encodeMaybeTagged encodeString
      }
    >>> encodeOptionalProps
      { optionalA: ade $ encodeInt
      , optionalB: ade $ encodeString
      }

Typeclass-based codec where some fields are optional

type Baz =
  { a :: { foo :: Boolean }
  , b :: Either Int (Array String)
  , c :: Maybe String                    -- required field using tagged Maybe approach
  , optionalA :: Optional (Maybe Int)    -- decodes to Nothing if field is missing.
  , optionalB :: Optional (Maybe String) -- decodes to Nothing if field is missing.
  }

bazDecoder :: JsonDecoder (Doc GraphicsParam) Baz
bazDecoder = decodeJson

bazEncoder :: Baz -> Json
bazEncoder = encodeJson

Typeclass-based codec where some instances are implemented via runtime-configured implementations

See Decoding.purs, which as of the time of writing, outputs:

### Typeclass (Local Overrides) Output:
Starting record: 
{ stringNormal: "hello"
, stringOverride: "+"
, tupleNormal: (Tuple "left" "right")
, tupleSwap: (Tuple "left" "right")
, tupleMultiOverride: (Tuple "left" "+")
}
Encoded Json: 
{
  "tupleSwap": [
    "left",
    "right"
  ],
  "tupleNormal": [
    "left",
    "right"
  ],
  "tupleMultiOverride": [
    "left",
    "+"
  ],
  "stringOverride": "+",
  "stringNormal": "hello"
}
Normal decoded value: 
{ stringNormal: "hello"
, stringOverride: "+"
, tupleNormal: (Tuple "left" "right")
, tupleSwap: (Tuple "left" "right")
, tupleMultiOverride: (Tuple "left" "+")
}
Locally-overridden decoded value: 
{ stringNormal: "hello"
, stringOverride: "1 + 1 == 2"
, tupleNormal: (Tuple "left" "right")
, tupleSwap: (Tuple "right" "left")
, tupleMultiOverride: (Tuple "1 + 1 == 2" "left")
}

purescript-json-codecs

Design

Error Messages for test/Main.purs

PrimitiveJsonError:

Doc Void

Doc GraphicsParam