Add recipes

[mlms13]

I was looking through the fp-ts recipes, and it would be amazing for us to have something similar. No need for a full-blown open source app demonstrating every way in which you might want to use Relude, just an ever-expanding collection of "here's how you solve exactly this problem..."

Some ideas:

• Utilities
  • How to make a custom type implement typeclasses like EQ and ORD
  • How to use custom typeclass implementations to get "extension" functions for free
  • How to integrate with some of bs-deriving's abilities
• Integrate with JS
  • Convert between JS Promise and Relude IO
  • Dealing with JS exceptions
• HTTP
  • How to make a request with Relude Fetch
  • How to integrate with decoding options like bs-decode
• React
  • How to trigger an HTTP effect inside a reducer
  • How to map IO effects into actions
  • How to model async state using AsyncData
  • How to render async state

[mlms13]

Also, to anyone else who may see this, please feel free to add suggestions! I just brainstormed this list off the top of my head in a few minutes, so I probably missed a lot of things.

[johnhaley81]

@mlms13 I can definitely help with this. Is there a particular place where you are thinking these should live?

[mlms13]

Seems like there are two options:

1. We just publish a static website with examples in markdown files

   • Super easy
   • Can live in the main Relude repo
   • No parsing, typechecking... no errors if Relude APIs change.

2. We create a new relude-recipes repo

   • Slightly more work to set up
   • Would each recipe have its own bsconfig and package.json?
   • Might be harder to keep each recipe narrowly focused
   • Easy for people to fork and play around with real code

[johnhaley81]

I think option 1 is the best way to get started. It can always get moved out later if the other things become a necessity

[andywhite37]

Just to throw it out there, you can put stuff in the docs/ folder, and link to it using the docsify.js stuff that we have now. Michael just deleted a bunch of the API-level stuff in favor of the odoc, but you can add new markdown files in there for recipes.

Or you could just add tests to the project that demonstrate some of the recipes. That way they will be compiled and tested along with everything else.

[mlms13]

Cool, sold. Once I merge the odoc PR (hopefully today!) which changes the docs folder a bit, we can create ./docs/recipes and start putting Markdown files in there.

I'm hoping to have a centralized place to show off recipes for e.g. relude-fetch and relude-reason-react (which have their own tests, but things are a bit more scattered). And unlike tests, I think it could be helpful to show how to chain a few things together, instead of just showing one function at a time.

[ajrouvoet]

@mlms13 You asked me to drop things here that require documentation/recipes.
Something I just ran into is that apparently open Relude is not the way to use this library.

But I had to find that out by trying to find out via the github issues why it broke my build (shadows Js, so that Js.t cannot be found by ReactReason!). I got lucky that I found it quickly, but that could've ruined my day ;-)

[mlms13]

I was just working on writing the api docs for the Relude and Relude.Globals modules that will make this clear, but it's absolutely a good call to show the open Relude.Globals pattern consistently in the recipes as well.

[ajrouvoet]

I also had quite a lengthy discussion on Discord today about performance and api design. I always like if docs are explicit about complexity of operations. Especially as a beginner it is a way to understand the implementation a bit better.

[mlms13]

Yeah, I've loved that the Purescript docs are very clear which functions on collections are O(1) vs O(n) vs ...whatever. I'm trying to improve those docs with more inline examples, and I'll also try to make some notes about complexity as well.

[johnhaley81]

@mlms13 what's the best way to move this forward? Should I just create that directory in ./docs/recipes and start putting markdown files in there?

[andywhite37]

I think that would be fine as a starting point - you can link to those from the sidebar markdown file.