This module introduces a Router that produces "correct-by-construction" URL encoding and decoding from any Haskell algebraic data type. This Router can be used in conjunction with uriSub or routeSub to perform client-side routing. Further it also supports the construction of type-safe links in any View model action via the href_ function exported from this module.

This module can be used in two ways, one is the manual construction of a Router as seen below.

data Route = Widget Int
   deriving (Show, Eq)

instance Router Route where
  routeParser = routes [ Widget <$> (path "widget" *> capture) ]
  fromRoute (Widget value) = [ toPath "widget", toCapture value ]

main :: IO ()
main = print (runRouter "widget10" router)

> Right (Widget "widget" 10)

The second way is using the Generic deriving mechanism. This should ensure that

{-# LANGUAGE DerivingStrategies #-}
{-# LANGUAGE DeriveAnyClass     #-}
{-# LANGUAGE DeriveGeneric      #-}

data Route
 = About
 | Home
 | Widget (Capture "thing" Int) (Path "foo") (Capture "other" MisoString) (QueryParam "bar" Int)
 deriving stock (Generic, Show)
 deriving anyclass Router

The Generic deriving works by converting the constructor name to a path so

test :: Either RoutingError Route
test = toRoute "/widget/23/foo/okay?bar=0"

Decodes as

Right (Widget (Capture 23) (Path "foo") (Capture "okay") (QueryParam (Just 0)))

The order of Capture and Path matters when defined on your sum type. The order of QueryParam and QueryFlag does not.

The router is "reversible" which means it can produce type-safe links using the href_ function.

prettyRoute $ Widget (Capture 23) (Path ("foo")) (Capture ("okay")) (QueryParam (Just 0))
"/widget/23/foo/okay?bar=0"

This can be used in conjunction with the href_ field below to embed type safe links into miso View model action code.

button_ [ Miso.Router.href_ (Widget 10) ] [ "click me" ]

Note: the Index constructor is name special, it used to encode the `"/"` path.

data Route = Index
  deriving stock (Show, Eq)
  deriving anyclass (Router)

main :: IO ()
main = print (fromRoute Index)

-- "/"

Lastly, camel-case constructors only use the first hump of the camel.

data Route = Index | FooBar
  deriving anyclass Router
  deriving stock (Show, Eq, Generic)

main :: IO ()
main = print (prettyRoute FooBar)

"/foo"