README.md · rowtype-yoga/purescript-yoga-json

git.iko.soy/rowtype-yoga/purescript-yoga-json

rowtype-yoga/purescript-yoga-json/README.md

67 lines 2.4 kB history raw

1# purescript-yoga-json

3**Note**: This is a fork of [simple-json](https://github.com/justinwoo/purescript-simple-json) ([MIT Licence](./LICENSE/simple-json.LICENSE)).

5## Table of Contents

6* [usage](#usage)

7* [migrate from `simple-json`](#migrate-from-purescript-simple-json)

9## Usage

11```purescript

12import Yoga.JSON as JSON

14serialised :: String

15serialised =

16 JSON.writeJSON { first_name: "Lola", last_name: "Flores" }

17```

19Check out the tests for how to encode/decode increasingly complex types.

21## Migrate from `purescript-simple-json`

23`purescript-yoga-json` is almost (read below if you use variants) a drop-in replacement for `purescript-simple-json`. Just change the imports from `Simple.JSON` to `Yoga.JSON`.

25## Additions over `simple-json`

27### Errors

28yoga-json will actually report multiple errors at once in the case of records, objects, and arrays.

29There's also a way to make errors more readable with `renderHumanError`:

30(e.g. `Must provide a value of type 'Int' instead of 'Object' at $.a.b.c.d[1]`)

33### Tuples

34There is an inbuilt codec for `Tuple`s thanks to @ursi

35`yoga-json` represents tuples as arrays in JSON.

37### Eithers

38There is an inbuilt codec for `Either`s.

39`yoga-json` represents eithers as objects with a `type` and a `value` tag in JSON.

41### JSDate and DateTime

42Both are encoded as ISO8601 strings as spat out by `JSDate.toISOString`.

44### Generics

45It includes @justinwoo's codecs for en- and decoding generics inspired by

46[simple-json-generics](https://github.com/justinwoo/purescript-simple-json-generics)

48It is possible to customise the representation of enums, tagged sum types, and untagged sum types via options.

50### BigInts

51There is an inbuilt codec for `BigInt`. Writing a `BigInt` however will result in a String. This is a current limitation of JavaScript and the only way around it - it seems - is writing your own JSON.stringify method (which is out of scope of this project).

53## Differences to `simple-json`

55### 💣 Variant codec

56If you want to emulate `simple-json`'s format you may use the newtype `TaggedVariant`

58```purescript

59type YourVariantRow = ( a :: Int, b :: String )

60type YourVariant = Variant YourVariantRow

61x :: YourVariant

62x = inj (Proxy :: Proxy "a") 5

63-- encoded = writeJSON x

64-- ^ Let's say you had this before

65-- You can now do:

66encoded = writeJSON (TaggedVariant "type" "value" x)

67```