Document the `Data.Codec.Argonaut.Migration` module

garyb / purescript-codec-argonaut

Bi-directional JSON codecs for argonaut

MIT License

39 stars 16 forks source link

Document the `Data.Codec.Argonaut.Migration` module #21

Closed joneshf closed 5 years ago

joneshf commented 5 years ago

We discussed on Slack about documenting the motivation behind the Data.Codec.Argonaut.Migration module. Here's what I realized while discussing yesterday:

The module is concerned with forward migrations of JSON objects.
Forward migrations can be implemented with the Functor instance for Data.Codec.GCodec _ _ _.
Backward and forward migrations can be implemented with the Profunctor instance for Data.Codec.GCodec _ _.

I tried to capture those realizations. Let me know if there's different wording or if I missed the mark. More than happy to make any changes.

garyb commented 5 years ago

This looks great to me :+1:

Do you think it's also worth mentioning the (<~<) / (>~>) codec composition operators and that sometimes even profunctor is not enough? (In that remapping that way only allows the migration to succeed, you need to dip down even deeper to construct a codec that can fail in a new way). I can write this part, just wondered if you thought that info belongs here too.

joneshf commented 5 years ago

For sure! It took me longer than I like to admit that you have to use (<~<)/(>~>) to make migrations work (multiple days). Anything in that regard would be useful.

garyb commented 5 years ago

Eep, sorry about that! I should perhaps re-export those operators from this module too. I'll make a new PR with the further changes anyway. Thanks!

joneshf commented 5 years ago

No worries. Using this package has been really nice. Thanks for making it!.