jordanmartinez/purescript-json-codecs

A unidirectional value-based JSON codec library.

purescript-json-codecs

A unidirectional value-based JSON codec library.

Whether this is more performant than other options is still being clarified. See the benchmarks.

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 "does not allow custom error messages" type, JsonDecodeError
  • Allow me to specify the order in which to encode something
  • Allow me the ability to rename fields when encoding/decoding

Improve error messages:

• on type mismatch errors, show me what you expected AND got, not just what was expected
• allow me to write custom error messages

Provide record syntax that distinguishes between

• when decoding
  • optional fields: whether a field is required or optional
  • renaming: decoding a key "foo" but putting it in a record label "bar"
• when encoding
  • order of fields: the order in which to encode fields
  • renaming: encoding a record label "bar" but encoding it as "foo" in the JSON
• See snapshots

For an example of decoding text and encoding examples, see ./test/test-output.txt

License

• codec - Copyright (c) 2019 Gary Burgess (MIT)
• codec-argonaut - Copyright (c) 2017 Gary Burgess (MIT)
• argonaut-codec - Copyright (c) 2020 PureScript Contrib (MIT)

purescript-json-codecs's Issues

Figure out best way to add the `Field` hint

Right now, nothing is using the Field hint. Ideally, that would happen with Record, but i'm not yet sure how I want to define this in the code. Perhaps a sum type for each of the cases?

• NoHint - doesn't add a hint
• ReuseKeyHint - Reuses the label under which the value is decoded
• NamedHint - uses the specified label (e.g. if the JSON label doesn't match the end-type's label)

Verify unidirectional decoder and encoders are actually bidirectional

I'm not sure these are bidirectional, but it should probably be checked just in case.

Add codecs for `Generic`

Reconsider default color for `AnsiDodoError`

See https://github.com/JordanMartinez/purescript-json-codecs#doc-graphicsparam

I think the colors for the error message could be improved, but I'm not yet sure what that should be.

Write documentation

Meaning, documentation comments within the source code itself. The DESIGN.md file already covers the overview of the design.

Topics include:

• using the pje identity function to remove type variables in records
• best practices for adding decoding context to bidi codecs
• ideas for overriding existing error types (e.g. colors used in the AnsiDodoError)

The `fix` function stack overflows

I was writing another benchmark, this time for a recursive data structure. While argonaut-codec (class-based) and codec-argonaut (value-based) worked fine, mine stack overflows.

Add benchmarks to compare against other libs

I need to find a good JSON codec benchmark as an example to follow.

Figure out best way for adding context to bidirectional codecs

This will use a lot of lcmap to map over the DecoderFn at various parts.

Move all shared error messages into the 'Messages.purs' file

Idea here is to have the same error message regardless of whether one is using the bidirectional/unidirectional class/value codec.