rgrempel / elm-http-decorators / Http.Decorators

This module contains several functions that build on the elm-lang/http package. Note that interpretStatus and promoteError are no longer included, because the Http module now does what they used to do.

For new projects, I would recommend using lukewestby/elm-http-builder instead of this package. It is capable of doing everything this package does, and more.

Transparent Requests


type alias RawRequest a =
{ method : String
, headers : List Http.Header
, url : String
, body : Http.Body
, expect : Http.Expect a
, timeout : Maybe Basics.Float
, withCredentials : Basics.Bool 
}

The Request type in the Http module is opaque, in the sense that once you have a Request, you cannot extract its parts in order to construct a different Request. The RawRequest type is a workaround for that, allowing you to work with the parts of a request.

You can construct a RawRequest manually, by filling in its parts. The various parts have the same meaning as the parameters to Http.request.

req : RawRequest String
req =
    { method = "GET"
    , headers = [ header "X-Test-Header" "Foo" ]
    , url = "http://elm-lang.org"
    , body = Http.emptyBody
    , expect = Http.expectString
    , timeout = Nothing
    , withCredentials = False
    }

Alternatively, you can construct a RawRequest by using defaultGet, defaultGetString, or defaultPost to fill in some defaults. These functions are like Http.get, Http.getString and Http.post, except that they return a RawRequest which you can further customize, rather than an opaque Request.

req : RawRequest String
req =
    let
        default =
            defaultGetString "http://elm-lang.org"
    in
    { default | headers = [ header "X-Test-Header" "Foo" ] }

Once you have a RawRequest, you can use toRequest to turn it into a Request that the Http module can use. Alternatively, you can sendRaw or toTaskRaw to turn the RawRequest directly into a Cmd or Task.

defaultPost : String -> Http.Body -> Json.Decode.Decoder a -> RawRequest a

Like Http.post, but returns a RawRequest that you could further customize.

You can then use toRequest to make an actual Http.Request, or supply the RawRequest to sendRaw or toTaskRaw.

defaultGet : String -> Json.Decode.Decoder a -> RawRequest a

Like Http.get, but returns a RawRequest String that you could further customize.

You can then use toRequest to make an actual Http.Request, or supply the RawRequest to sendRaw or toTaskRaw.

defaultGetString : String -> RawRequest String

Like Http.getString, but returns a RawRequest String that you could further customize.

You can then use toRequest to make an actual Http.Request, or supply the RawRequest to sendRaw or toTaskRaw.

req : RawRequest String
req =
    let
        default =
            defaultGet "http://elm-lang.org"
    in
    { default | timeout = Just (1 * Time.second) }

sendRaw : (Result Http.Error a -> msg) -> RawRequest a -> Platform.Cmd.Cmd msg

Like Http.send, but uses a RawRequest instead of a Request.

toTaskRaw : RawRequest a -> Task Http.Error a

Like Http.toTask, but uses a RawRequest instead of a Request.

toRequest : RawRequest a -> Http.Request a

Turns a RawRequest a into an Http.Request a. This is just another name for Http.request.

Cache busting

cacheBusterUrl : String -> Task x String

Given a URL, add a 'cache busting' parameter of the form '?cacheBuster=219384729384', where the number is derived from the current time. The purpose of doing this would be to help defeat any caching that might otherwise take place at some point between the client and server.

Often you won't need to call this directly -- you can use addCacheBuster, taskWithCacheBuster or sendWithCacheBuster instead.

urlWithTime : Task x String
urlWithTime =
    cacheBusterUrl "http://elm-lang.org"


-- Should resolve to something like "http://elm-lang.org?param=7&cacheBuster=12348257"
urlWithTime2 : Task x String
urlWithTime2 =
    cacheBusterUrl "http://elm-lang.org?param=7"

addCacheBuster : RawRequest a -> Task x (RawRequest a)

Given a RawRequest, add a cache-busting parameter to the URL. This uses cacheBusterUrl internally to generate the parameter.

Note that the resulting task will resolve with the modified RawRequest, which will itself need to be turned into a Task or Cmd to be actually executed. Thus, you often would not need to call this directly -- you could use taskWithCacheBuster or sendWithCacheBuster instead. You would only need addCacheBuster in cases where you need to do some further processing of the resolved RawRequest before turning it into a Task or a Cmd.

taskWithCacheBuster : RawRequest a -> Task Http.Error a

Given a RawRequest, add a cache-busting parameter to the URL and return a Task that executes the request.

This is useful in cases where the resulting Task is part of some larger chain of tasks. In cases where you are just going to turn this very Task into a Cmd, you could use sendWithCacheBuster instead.

sendWithCacheBuster : (Result Http.Error a -> msg) -> RawRequest a -> Platform.Cmd.Cmd msg

Given a RawRequest, add a cache-busting parameter to the URL and return a Cmd that executes the request.

This is a convenience for cases in which your RawRequest is meant to result in a simple Cmd. For more complex cases, you can use taskWithCacheBuster, addCacheBuster or cacheBusterUrl, depending on how much further customization you need.