API discussion

[jdegoes]

A ticket to discuss the API.

The other day I was thinking something like this could work:

ajax :: forall e. AjaxRequest -> Aff (ajax :: AJAX | e) AjaxResponse

type AjaxRequest = {
  url :: String,
  method :: Method,
  headers :: StrMap String,
  content :: Content,
  ...
}

type AjaxResponse = {
  headers :: StrMap String
  ...
}

ajaxRequestDefaults :: String -> AjaxRequest

Then a separate module could define combinators, such as:

GET :: AjaxRequest -> AjaxRequest

contentType :: MimeType -> AjaxRequest -> AjaxRequest
...
runAjax :: String -> (AjaxRequest -> AjaxRequest) -> Aff (ajax :: AJAX | e) AjaxResponse
runAjax url f = ajax (f (ajaxRequestDefaults url))

So you'd write code like:

runAjax "http://foo.com" $ GET >>> contentType applicationJson

But I'm sure there are better APIs. Let's discuss here if you have any ideas.

[garyb]

I suppose one disadvantage of the combinator approach is you can make nonsensical requests with them, like GET <<< POST or using contentType multiple times, etc. Obviously the resulting request is still fine, but I mean if you follow the process of how it's build it doesn't make much sense. Perhaps still worth it for the better composability?

Also actually we'd have to call them get, put, post, ... as names starting with an uppercase letter are reserved for types and data constructors.

[garyb]

I should have time to get somewhere with this tonight, by the way.

[cryogenian]

I think FreeMonad DSL can mimic records and be very well composable:

-- free
call cb eb =
  mkAffJax "http://foo.com" $ do
    method GET
    contentType ApplicationJson
    header "foo" "bar"
    header "bar" "baz" 
    success cb
    error eb
-- record
call' cb eb =
  mkAffJax {
    url: "http://foo.com",
    method: GET,
    contentType: ApplicationJson,
    headers: [Tuple "foo" "bar",
              Tuple "bar" "baz"],
    success: cb,
    error: eb
    }

get = method GET
json = contentType ApplicationJson
headers = do
  header "foo" "bar"
  header "bar" "baz"

call'' = do
    get
    json
    headers 

We can use phantom types also to check if there setted method and url (and that they are setted only once)

data AjaxRequest m u h s e =
  AjaxRequest {method :: m, url :: u, headers :: [h], success :: s, error :: [e]}

get :: forall u h s e. AjaxRequest NoMethod u h s e -> AjaxRequest Method u h s e
get (AjaxRequest r) = AjaxRequest $ r{method = GET} 

What is the target? Couldn't we just wrap Aff purescript-simple-dom Ajax?

[jdegoes]

Yeah, phantom types can solve the problem of setting the same value more than once. Free could work here, too, if you like do syntax for this (very blaze-ish), of course there will be no callbacks since we'll be using Aff.

It's possible, of course, to build this on top of simple-dom Ajax, but I would prefer fewer dependencies (all other things being equal).

[garyb]

Yeah, I've been looking at using a free monad to do this too.

Using Ajax from purescript-simple-dom is one way to go, but that has a DOM effect for some reason, and also defines all its own HTTP verbs rather than using something like purescript-http.

[jdegoes]

Btw we need support for custom HTTP verbs, since it's supported by XmlHttpRequestObj and also required by the SlamEngine API.

[cryogenian]

I've not tried to use free after it's updated to tailrec. If it is too slow we can use simple State or ST

data AffJaxConfig ... -- same thing with fantom types 


method :: forall a. HttpMethod a -> State AffJaxConfig Unit
method m = do
  modify (\(AffJaxConfig r) -> AffJaxConfig $ r{method = m})

mkAffJax :: forall u. String -> State AffJaxConfig u -> AffJax
mkAffJax url config =
  mkAffJax' url $ execState config emptyConfig

mkAffJax' :: String -> AffJaxConfig -> AffJax 

[garyb]

I didn't get quite as far with this as I'd hoped tonight, but should have something for discussion and review tomorrow.

[jdegoes]

@garyb How's this coming along?

[garyb]

Got a commit coming in about half an hour :)