Reflex.Dom.Xhr

A module for performing asynchronous HTTP calls from JavaScript using the XMLHttpRequest API (essentially AJAX). Despite the name, there is nothing whatsoever specific to XML.

The API has two components:

• convenient functions for common usecases like GET and POST requests to APIs using JSON.
• a flexible set of functions for creating and executing arbitrary requests and handling responses.

Common Patterns

Functions that conveniently expose common uses like GET and POST to JSON APIs.

getAndDecode :: (MonadIO m, MonadJSM (Performable m), PerformEvent t m, HasJSContext (Performable m), TriggerEvent t m, FromJSON a) => Event t Text -> m (Event t (Maybe a))

Simplified interface to GET URLs and return decoded results.

getMay :: (Monad m, Reflex t) => (Event t a -> m (Event t b)) -> Event t (Maybe a) -> m (Event t (Maybe b))

postJson :: ToJSON a => Text -> a -> XhrRequest Text

Create a POST request from an URL and thing with a JSON representation

decodeXhrResponse :: FromJSON a => XhrResponse -> Maybe a

Convenience function to decode JSON-encoded responses.

decodeText :: FromJSON a => Text -> Maybe a

General Request API

This is the most general flow for sending XHR requests:

1. Create an Event stream of XhrRequest records (ie Event t (XhrRequest a)). The records configure the request, and the Event controls when the request or requests are actually sent.
2. Plug the Event t (XhrRequest a) into one of the functions for performing requests like performRequestAsync.
3. Consume the resulting stream of XhrResponse events, parsing the body of the response however appropriate. A really common pattern is turning the Event into a Dynamic with holdDyn or a related function.

Here is an example of calling a search API whenever the user types in a text input field and printing the result on the page:

url query = "http://example.com/search?query=" <> query

search queries = do
  responses <- performRequestAsync $ toRequest <$> queries
  return $ view xhrResponse_responseText <$> responses
  where toRequest query = XhrRequest "GET" (url query) def

main = mainWidget $ do
  input <- textInput def
  let queries = updated $ input ^. textInput_value
  results <- search queries
  asText <- holdDyn "No results." $ pack . show <$> results
  dynText asText

XHR Requests

data XhrRequest a

Constructors

XhrRequest

Fields

• _xhrRequest_method :: Text
• _xhrRequest_url :: Text
• _xhrRequest_config :: XhrRequestConfig a

Instances

Functor XhrRequest

Defined in Reflex.Dom.Xhr

Methods

fmap :: (a -> b) -> XhrRequest a -> XhrRequest b

(<$) :: a -> XhrRequest b -> XhrRequest a

Eq a => Eq (XhrRequest a)

Defined in Reflex.Dom.Xhr

Methods

(==) :: XhrRequest a -> XhrRequest a -> Bool

(/=) :: XhrRequest a -> XhrRequest a -> Bool

Ord a => Ord (XhrRequest a)

Defined in Reflex.Dom.Xhr

Methods

compare :: XhrRequest a -> XhrRequest a -> Ordering

(<) :: XhrRequest a -> XhrRequest a -> Bool

(<=) :: XhrRequest a -> XhrRequest a -> Bool

(>) :: XhrRequest a -> XhrRequest a -> Bool

(>=) :: XhrRequest a -> XhrRequest a -> Bool

max :: XhrRequest a -> XhrRequest a -> XhrRequest a

min :: XhrRequest a -> XhrRequest a -> XhrRequest a

Read a => Read (XhrRequest a)

Defined in Reflex.Dom.Xhr

Methods

readsPrec :: Int -> ReadS (XhrRequest a)

readList :: ReadS [XhrRequest a]

readPrec :: ReadPrec (XhrRequest a)

readListPrec :: ReadPrec [XhrRequest a]

Show a => Show (XhrRequest a)

Defined in Reflex.Dom.Xhr

Methods

showsPrec :: Int -> XhrRequest a -> ShowS

show :: XhrRequest a -> String

showList :: [XhrRequest a] -> ShowS

data XhrRequestConfig a

Constructors

XhrRequestConfig

Fields

• _xhrRequestConfig_headers :: Map Text Text
• _xhrRequestConfig_user :: Maybe Text
• _xhrRequestConfig_password :: Maybe Text
• _xhrRequestConfig_responseType :: Maybe XhrResponseType
• _xhrRequestConfig_sendData :: a
• _xhrRequestConfig_withCredentials :: Bool
• _xhrRequestConfig_responseHeaders :: XhrResponseHeaders

Instances

Functor XhrRequestConfig

Defined in Reflex.Dom.Xhr

Methods

fmap :: (a -> b) -> XhrRequestConfig a -> XhrRequestConfig b

(<$) :: a -> XhrRequestConfig b -> XhrRequestConfig a

Eq a => Eq (XhrRequestConfig a)

Defined in Reflex.Dom.Xhr

Methods

(==) :: XhrRequestConfig a -> XhrRequestConfig a -> Bool

(/=) :: XhrRequestConfig a -> XhrRequestConfig a -> Bool

Ord a => Ord (XhrRequestConfig a)

Defined in Reflex.Dom.Xhr

Methods

compare :: XhrRequestConfig a -> XhrRequestConfig a -> Ordering

(<) :: XhrRequestConfig a -> XhrRequestConfig a -> Bool

(<=) :: XhrRequestConfig a -> XhrRequestConfig a -> Bool

(>) :: XhrRequestConfig a -> XhrRequestConfig a -> Bool

(>=) :: XhrRequestConfig a -> XhrRequestConfig a -> Bool

max :: XhrRequestConfig a -> XhrRequestConfig a -> XhrRequestConfig a

min :: XhrRequestConfig a -> XhrRequestConfig a -> XhrRequestConfig a

Read a => Read (XhrRequestConfig a)

Defined in Reflex.Dom.Xhr

Methods

readsPrec :: Int -> ReadS (XhrRequestConfig a)

readList :: ReadS [XhrRequestConfig a]

readPrec :: ReadPrec (XhrRequestConfig a)

readListPrec :: ReadPrec [XhrRequestConfig a]

Show a => Show (XhrRequestConfig a)

Defined in Reflex.Dom.Xhr

Methods

showsPrec :: Int -> XhrRequestConfig a -> ShowS

show :: XhrRequestConfig a -> String

showList :: [XhrRequestConfig a] -> ShowS

a ~ () => Default (XhrRequestConfig a)

Defined in Reflex.Dom.Xhr

Methods

def :: XhrRequestConfig a

xhrRequest :: Text -> Text -> XhrRequestConfig a -> XhrRequest a

Construct a request object from method, URL, and config record.

xhrRequestConfig_headers :: forall a. Lens' (XhrRequestConfig a) (Map Text Text)

xhrRequestConfig_password :: forall a. Lens' (XhrRequestConfig a) (Maybe Text)

xhrRequestConfig_responseType :: forall a. Lens' (XhrRequestConfig a) (Maybe XhrResponseType)

xhrRequestConfig_sendData :: forall a a. Lens (XhrRequestConfig a) (XhrRequestConfig a) a a

xhrRequestConfig_user :: forall a. Lens' (XhrRequestConfig a) (Maybe Text)

xhrRequestConfig_withCredentials :: forall a. Lens' (XhrRequestConfig a) Bool

xhrRequestConfig_responseHeaders :: forall a. Lens' (XhrRequestConfig a) XhrResponseHeaders

xhrRequest_config :: forall a a. Lens (XhrRequest a) (XhrRequest a) (XhrRequestConfig a) (XhrRequestConfig a)

xhrRequest_method :: forall a. Lens' (XhrRequest a) Text

xhrRequest_url :: forall a. Lens' (XhrRequest a) Text

Performing Requests

performMkRequestAsync :: (MonadJSM (Performable m), HasJSContext (Performable m), PerformEvent t m, TriggerEvent t m, IsXhrPayload a) => Event t (Performable m (XhrRequest a)) -> m (Event t XhrResponse)

Given Event with an action that creates a request, build and issue the request when the Event fires. Returns Event of corresponding response.

performMkRequestsAsync :: (MonadJSM (Performable m), HasJSContext (Performable m), PerformEvent t m, TriggerEvent t m, Traversable f, IsXhrPayload a) => Event t (Performable m (f (XhrRequest a))) -> m (Event t (f XhrResponse))

Builds and issues a collection of requests when the supplied Event fires. When ALL requests from a given firing complete, the results are collected and returned via the return Event.

performRequestAsync :: (MonadJSM (Performable m), HasJSContext (Performable m), PerformEvent t m, TriggerEvent t m, IsXhrPayload a) => Event t (XhrRequest a) -> m (Event t XhrResponse)

Given Event of request, issue them when the Event fires. Returns Event of corresponding response.

performRequestAsyncWithError :: (MonadJSM (Performable m), HasJSContext (Performable m), PerformEvent t m, TriggerEvent t m, IsXhrPayload a) => Event t (XhrRequest a) -> m (Event t (Either XhrException XhrResponse))

Given Event of requests, issue them when the Event fires. Returns Event of corresponding responses.

The request is processed asynchronously, therefore handling does not block or cause a delay while creating the connection.

performRequestsAsync :: (MonadJSM (Performable m), HasJSContext (Performable m), PerformEvent t m, TriggerEvent t m, Traversable f, IsXhrPayload a) => Event t (f (XhrRequest a)) -> m (Event t (f XhrResponse))

Issues a collection of requests when the supplied Event fires. When ALL requests from a given firing complete, the results are collected and returned via the return Event.

performRequestsAsyncWithError :: (MonadJSM (Performable m), HasJSContext (Performable m), PerformEvent t m, TriggerEvent t m, Traversable f, IsXhrPayload a) => Event t (f (XhrRequest a)) -> m (Event t (f (Either XhrException XhrResponse)))

Issues a collection of requests when the supplied Event fires. When ALL requests from a given firing complete, the results are collected and returned via the return Event.

The requests are processed asynchronously, therefore handling does not block or cause a delay while creating the connection.

Order of request execution and completion is not guaranteed, but order of creation and the collection result is preserved.

XHR Responses

data XhrResponse

Constructors

XhrResponse

Fields

• _xhrResponse_status :: Word
• _xhrResponse_statusText :: Text
• _xhrResponse_response :: Maybe XhrResponseBody
• _xhrResponse_responseText :: Maybe Text
• _xhrResponse_headers :: Map Text Text

data XhrResponseBody

Constructors

XhrResponseBody_Default Text

XhrResponseBody_Text Text

XhrResponseBody_Blob Blob

XhrResponseBody_ArrayBuffer ByteString

data XhrResponseHeaders

Constructors

OnlyHeaders (Set Text)

Parse a subset of headers from the XHR Response

AllHeaders

Parse all headers from the XHR Response

Instances

Eq XhrResponseHeaders

Defined in Reflex.Dom.Xhr

Methods

(==) :: XhrResponseHeaders -> XhrResponseHeaders -> Bool

(/=) :: XhrResponseHeaders -> XhrResponseHeaders -> Bool

Ord XhrResponseHeaders

Defined in Reflex.Dom.Xhr

Methods

compare :: XhrResponseHeaders -> XhrResponseHeaders -> Ordering

(<) :: XhrResponseHeaders -> XhrResponseHeaders -> Bool

(<=) :: XhrResponseHeaders -> XhrResponseHeaders -> Bool

(>) :: XhrResponseHeaders -> XhrResponseHeaders -> Bool

(>=) :: XhrResponseHeaders -> XhrResponseHeaders -> Bool

max :: XhrResponseHeaders -> XhrResponseHeaders -> XhrResponseHeaders

min :: XhrResponseHeaders -> XhrResponseHeaders -> XhrResponseHeaders

Read XhrResponseHeaders

Defined in Reflex.Dom.Xhr

Methods

readsPrec :: Int -> ReadS XhrResponseHeaders

readList :: ReadS [XhrResponseHeaders]

readPrec :: ReadPrec XhrResponseHeaders

readListPrec :: ReadPrec [XhrResponseHeaders]

Show XhrResponseHeaders

Defined in Reflex.Dom.Xhr

Methods

showsPrec :: Int -> XhrResponseHeaders -> ShowS

show :: XhrResponseHeaders -> String

showList :: [XhrResponseHeaders] -> ShowS

Default XhrResponseHeaders

Defined in Reflex.Dom.Xhr

Methods

def :: XhrResponseHeaders

data XhrResponseType

Constructors

XhrResponseType_Default

XhrResponseType_ArrayBuffer

XhrResponseType_Blob

XhrResponseType_Text

Instances

Eq XhrResponseType

Defined in Reflex.Dom.Xhr.ResponseType

Methods

(==) :: XhrResponseType -> XhrResponseType -> Bool

(/=) :: XhrResponseType -> XhrResponseType -> Bool

Ord XhrResponseType

Defined in Reflex.Dom.Xhr.ResponseType

Methods

compare :: XhrResponseType -> XhrResponseType -> Ordering

(<) :: XhrResponseType -> XhrResponseType -> Bool

(<=) :: XhrResponseType -> XhrResponseType -> Bool

(>) :: XhrResponseType -> XhrResponseType -> Bool

(>=) :: XhrResponseType -> XhrResponseType -> Bool

max :: XhrResponseType -> XhrResponseType -> XhrResponseType

min :: XhrResponseType -> XhrResponseType -> XhrResponseType

Read XhrResponseType

Defined in Reflex.Dom.Xhr.ResponseType

Methods

readsPrec :: Int -> ReadS XhrResponseType

readList :: ReadS [XhrResponseType]

readPrec :: ReadPrec XhrResponseType

readListPrec :: ReadPrec [XhrResponseType]

Show XhrResponseType

Defined in Reflex.Dom.Xhr.ResponseType

Methods

showsPrec :: Int -> XhrResponseType -> ShowS

show :: XhrResponseType -> String

showList :: [XhrResponseType] -> ShowS

xhrResponse_response :: Lens' XhrResponse (Maybe XhrResponseBody)

xhrResponse_responseText :: Lens' XhrResponse (Maybe Text)

xhrResponse_status :: Lens' XhrResponse Word

xhrResponse_statusText :: Lens' XhrResponse Text

xhrResponse_headers :: Lens' XhrResponse (Map Text Text)

Deprecated

xhrResponse_body :: Lens' XhrResponse (Maybe Text)

Deprecated: Use xhrResponse_response or xhrResponse_responseText instead.

_xhrResponse_body :: XhrResponse -> Maybe Text

Deprecated: Use _xhrResponse_response or _xhrResponse_responseText instead.

Error Handling

data XhrException

Constructors

XhrException_Error

XhrException_Aborted

Instances

Eq XhrException

Defined in Reflex.Dom.Xhr.Exception

Methods

(==) :: XhrException -> XhrException -> Bool

(/=) :: XhrException -> XhrException -> Bool

Ord XhrException

Defined in Reflex.Dom.Xhr.Exception

Methods

compare :: XhrException -> XhrException -> Ordering

(<) :: XhrException -> XhrException -> Bool

(<=) :: XhrException -> XhrException -> Bool

(>) :: XhrException -> XhrException -> Bool

(>=) :: XhrException -> XhrException -> Bool

max :: XhrException -> XhrException -> XhrException

min :: XhrException -> XhrException -> XhrException

Read XhrException

Defined in Reflex.Dom.Xhr.Exception

Methods

readsPrec :: Int -> ReadS XhrException

readList :: ReadS [XhrException]

readPrec :: ReadPrec XhrException

readListPrec :: ReadPrec [XhrException]

Show XhrException

Defined in Reflex.Dom.Xhr.Exception

Methods

showsPrec :: Int -> XhrException -> ShowS

show :: XhrException -> String

showList :: [XhrException] -> ShowS

Exception XhrException

Defined in Reflex.Dom.Xhr.Exception

Methods

toException :: XhrException -> SomeException

fromException :: SomeException -> Maybe XhrException

displayException :: XhrException -> String

class IsXhrPayload a where

Minimal complete definition

sendXhrPayload

Methods

sendXhrPayload :: MonadJSM m => XMLHttpRequest -> a -> m ()

Instances

IsXhrPayload ()

Defined in Reflex.Dom.Xhr.Foreign

Methods

sendXhrPayload :: MonadJSM m => XMLHttpRequest -> () -> m ()

IsXhrPayload String

Defined in Reflex.Dom.Xhr.Foreign

Methods

sendXhrPayload :: MonadJSM m => XMLHttpRequest -> String -> m ()

IsXhrPayload ByteString

Defined in Reflex.Dom.Xhr.Foreign

Methods

sendXhrPayload :: MonadJSM m => XMLHttpRequest -> ByteString -> m ()

IsXhrPayload Text

Defined in Reflex.Dom.Xhr.Foreign

Methods

sendXhrPayload :: MonadJSM m => XMLHttpRequest -> Text -> m ()

IsXhrPayload ArrayBuffer

Defined in Reflex.Dom.Xhr.Foreign

Methods

sendXhrPayload :: MonadJSM m => XMLHttpRequest -> ArrayBuffer -> m ()

IsXhrPayload Blob

Defined in Reflex.Dom.Xhr.Foreign

Methods

sendXhrPayload :: MonadJSM m => XMLHttpRequest -> Blob -> m ()

IsXhrPayload Document

Defined in Reflex.Dom.Xhr.Foreign

Methods

sendXhrPayload :: MonadJSM m => XMLHttpRequest -> Document -> m ()

IsXhrPayload FormData

Defined in Reflex.Dom.Xhr.Foreign

Methods

sendXhrPayload :: MonadJSM m => XMLHttpRequest -> FormData -> m ()

JavaScript XMLHttpRequest Objects

XMLHttpRequest is the type of JavaScript's underlying runtime objects that represent XHR requests.

Chances are you shouldn't need these in day-to-day code.

data XMLHttpRequest

Functions for this inteface are in JSDOM.XMLHttpRequest. Base interface functions are in:

• JSDOM.XMLHttpRequestEventTarget
• JSDOM.EventTarget

Mozilla XMLHttpRequest documentation

Instances

PToJSVal XMLHttpRequest

Defined in JSDOM.Types

Methods

pToJSVal :: XMLHttpRequest -> JSVal

PFromJSVal XMLHttpRequest

Defined in JSDOM.Types

Methods

pFromJSVal :: JSVal -> XMLHttpRequest

ToJSVal XMLHttpRequest

Defined in JSDOM.Types

Methods

toJSVal :: XMLHttpRequest -> JSM JSVal

toJSValListOf :: [XMLHttpRequest] -> JSM JSVal

FromJSVal XMLHttpRequest

Defined in JSDOM.Types

Methods

fromJSVal :: JSVal -> JSM (Maybe XMLHttpRequest)

fromJSValUnchecked :: JSVal -> JSM XMLHttpRequest

fromJSValListOf :: JSVal -> JSM (Maybe [XMLHttpRequest])

fromJSValUncheckedListOf :: JSVal -> JSM [XMLHttpRequest]

MakeObject XMLHttpRequest

Defined in JSDOM.Types

Methods

makeObject :: XMLHttpRequest -> JSM Object

IsGObject XMLHttpRequest

Defined in JSDOM.Types

Methods

typeGType :: XMLHttpRequest -> JSM GType

IsEventTarget XMLHttpRequest

Defined in JSDOM.Types

IsXMLHttpRequestEventTarget XMLHttpRequest

Defined in JSDOM.Types

Constructors

newXMLHttpRequest :: (HasJSContext m, MonadJSM m, IsXhrPayload a) => XhrRequest a -> (XhrResponse -> JSM ()) -> m XMLHttpRequest

newXMLHttpRequestWithError

Arguments

:: (HasJSContext m, MonadJSM m, IsXhrPayload a)

=> XhrRequest a

The request to make.

-> (Either XhrException XhrResponse -> JSM ())

A continuation to be called once a response comes back, or in case of error.

-> m XMLHttpRequest

The XHR request, which could for example be aborted.

Make a new asyncronous XHR request. This does not block (it forks), and returns an XHR object immediately (which you can use to abort the XHR connection), and will pass an exception (XhrException) to the continuation if the connection cannot be made (or is aborted).

Fields

xmlHttpRequestGetReadyState :: MonadJSM m => XMLHttpRequest -> m Word

xmlHttpRequestGetResponseText :: (FromJSString result, MonadJSM m) => XMLHttpRequest -> m (Maybe result)

xmlHttpRequestGetStatus :: MonadJSM m => XMLHttpRequest -> m Word

xmlHttpRequestGetStatusText :: MonadJSM m => FromJSString result => XMLHttpRequest -> m result

xmlHttpRequestNew :: MonadJSM m => m XMLHttpRequest

xmlHttpRequestOnreadystatechange :: XMLHttpRequest -> EventM XMLHttpRequest Event () -> JSM (JSM ())

xmlHttpRequestOpen :: (ToJSString method, ToJSString url, ToJSString user, ToJSString password, MonadJSM m) => XMLHttpRequest -> method -> url -> Bool -> user -> password -> m ()

xmlHttpRequestSetRequestHeader :: (ToJSString header, ToJSString value, MonadJSM m) => XMLHttpRequest -> header -> value -> m ()

xmlHttpRequestSetResponseType :: MonadJSM m => XMLHttpRequest -> XMLHttpRequestResponseType -> m ()