purescript-boomboom

Disclaimer

Never hard code your urls again. Boomboom routing-duplex them all!

It was quite a nice coding challange and experiment for me, but I feel that routing-duplex exposes much cleaner and user friendly API at this moment. Please check it first!

Description

Bidirectional routing library with principled plumbing which provides easy to use generic sugar for variants and records.

Still β stage…

BoomBoom

The core type of this library is BoomBoom.BoomBoom which translates really to this simple record:

newtype BoomBoom tok a = BoomBoom { prs ∷ tok → Maybe { a ∷ a, tok ∷ tok }, ser ∷ a → tok }

So our BoomBoom tok a is a simple parser from tok to a and also a total serializer function in opposite direction. Composability of this type requires usually that tok has a Semigroup instance. For details check BoomBoom.BoomBoom module docs.

Typelevel interpretation and helpers

Let’s assume that we have routes from previous example and want to produce this serialization p1/sp1/1/2/3 result. To do this we have to build our variant by hand (as in previous example):

  serialize $ inj (SProxy ∷ SProxy "p1") (inj (SProxy ∷ SProxy "sp1") {x: 1, y: 2, z: 3})

This API is not really readable and easy to use as we have to nest all these inj functions with SProxy constructors.

In BoomBoom.Generic.Interpret you can find “type level interpreters” which are able to produce BoomBooms but also easy to use builders of values (variants/records) from “records tree”. Instead of building BoomBooms directly you should define your tree using provided constructors:

import BoomBoom.Generic.Interpret (V, R, B)
import BoomBoom.Strings (int)

desc = V
  { p1: V
      { sp1: R { x: B int, y: B int, z: B int }
      , sp2: B int
      }
  , p2: B int
  }

Now you can produce your BoomBoom value but also a builder:

import BoomBoom.Generic.Interpret (interpret)
import Type.Prelude (SProxy(..))

-- | Generate a builder
builder = interpret (SProxy ∷ SProxy "builder") desc

-- | Generate a BoomBoom
boomboom = interpret (SProxy ∷ SProxy "boomboom") desc

This builder is a record (for variants build up) or function (for records build up) which helps us build values ready for serialization. So for example this:

v = builder.p1.sp1 {x: 1, y: 2, z: 3}

Is equivalent of this:

v = inj (SProxy ∷ SProxy "p1") (inj (SProxy ∷ SProxy "sp1") {x: 1, y: 2, z: 3})

Now we can use this value and serialize it:

serialize boomboom v

Output (in case of BoomBoom.Strings serialization) value:

("p1":"sp1":"1":"2":"3":Nil)

Applicative API

And here is completely different approach which uses apply and BoomBoom.diverge (aka (>-)):

path :: BoomBoom String { x :: Int, y :: Int }
path = BoomBoom $
  { x: _, y: _ }
    <$> _.x >- int
    <* lit "test"
    <*> _.y >- int

main :: forall e. Eff (console :: CONSOLE | e) Unit
main = do
  log $ unsafeStringify (parse path ("8080":"test":"200":Nil))

  log (serialize path { x: 300, y: 800 })

Output values:

{"value0":{"x":8080,"y":200}}

-- | I've replaced here `Cons` with (:) to simplify reading
("300":"test":"800":Nil)

TODO

There is ongoing work for “API interpreters” which would generate records clients and server helpers but also docs etc.

Credits

• A lot of inspirations and crucial suggestions I received from @MonoidMusician. Thanks!

• Initial design of diverging instances was inspired by this @sebastiaanvisser answer.

• Name loosely inspired by this @notcome gist.