Merge pull request #127 from slamdata/next

More changes for the next release version

Author: garyb

.travis.yml

@@ -1,16 +1,15 @@
 language: node_js
 dist: trusty
 sudo: required
-node_js: 6
+node_js: stable
 install:
   - npm install bower -g
   - npm install
 script:
   - bower install --production
   - npm run -s build
   - bower install
-  - node ./test-server.js &
-  - sleep 2 && npm -s test
+  - npm run -s test
 after_success:
 - >-
   test $TRAVIS_TAG &&

README.md

@@ -28,36 +28,49 @@ module Main where
 
 import Prelude
 
+import Affjax as AX
+import Affjax.ResponseFormat as ResponseFormat
 import Data.Argonaut.Core as J
 import Data.Either (Either(..))
 import Data.HTTP.Method (Method(..))
 import Effect.Aff (launchAff)
-import Effect.Class (liftEffect)
-import Effect.Console (log)
-import Network.HTTP.Affjax as AX
-import Network.HTTP.Affjax.ResponseFormat as ResponseFormat
+import Effect.Class.Console (log)
 
 main = launchAff $ do
   res <- AX.request ResponseFormat.json (AX.defaultRequest { url = "/api", method = Left GET })
-  liftEffect $ log $ "GET /api response: " <> J.stringify res.response
+  case res.body of
+    Left err -> log $ "GET /api response failed to decode: " <> AX.printResponseFormatError err
+    Right json -> log $ "GET /api response: " <> J.stringify json
 ```
 
 (`defaultRequest` is a record value that has all the required fields pre-set for convenient overriding when making a request.)
 
-Or use of a number of helpers for common cases:
+There are also a number of helpers for common `get`, `post`, `put`, `delete`, and `patch` cases:
 
 ```purescript
-import Network.HTTP.Affjax.RequestBody as RequestBody
+import Affjax.RequestBody as RequestBody
 
 main = launchAff $ do
   res1 <- AX.get ResponseFormat.json "/api"
-  liftEffect $ log $ "GET /api response: " <> J.stringify res1.response
+  case res1.body of
+    Left err -> log $ "GET /api response failed to decode: " <> AX.printResponseFormatError err
+    Right json -> log $ "GET /api response: " <> J.stringify json
 
   res2 <- AX.post ResponseFormat.json "/api" (RequestBody.json (J.fromString "test"))
-  liftEffect $ log $ "POST /api response: " <> J.stringify res2.response
+  case res2.body of
+    Left err -> log $ "POST /api response failed to decode: " <> AX.printResponseFormatError err
+    Right json -> log $ "POST /api response: " <> J.stringify json
 ```
 
-See the module documentation for a full list of these helpers.
+See the [main module documentation](https://pursuit.purescript.org/packages/purescript-affjax/docs/Affjax) for a full list of these helpers and their variations.
+
+## Error handling
+
+There are two ways an Affjax request can fail: there's either some problem with the request itself, or the result that comes back is not as expected.
+
+For the first case, these errors will be things like the URL being invalid or the server not existing, and will occur in the `Aff` error channel. The [`try`](https://pursuit.purescript.org/packages/purescript-aff/docs/Effect.Aff#v:try) function can lift these errors out of the error channel so the result of a request becomes `Aff (Either Error (Response _))`.
+
+The latter case occurs when we did get a response for the request, but the result that came back could not be handled in the way that was expected. In these situations the `body` value of the `Response` will be a `Left` value with the error message describing what went wrong.
 
 ## Module documentation
 

package.json

@@ -11,7 +11,7 @@
     "express": "^4.14.0",
     "pulp": "^11.0.0",
     "purescript-psa": "^0.5.0",
-    "purescript": "slamdata/node-purescript#0.12",
+    "purescript": "^0.12.0",
     "rimraf": "^2.5.4",
     "xhr2": "^0.1.3"
   }

src/Network/HTTP/Affjax.js renamed to src/Affjax.js

@@ -68,7 +68,7 @@ exports._ajax = function () {
               var i = header.indexOf(":");
               return mkHeader(header.substring(0, i))(header.substring(i + 2));
             }),
-          response: platformSpecific.getResponse(xhr)
+          body: platformSpecific.getResponse(xhr)
         });
       };
       xhr.responseType = options.responseType;

src/Network/HTTP/Affjax.purs renamed to src/Affjax.purs

@@ -1,4 +1,4 @@
-module Network.HTTP.Affjax
+module Affjax
   ( RequestOptions, defaultRequest
   , Response
   , URL
@@ -12,16 +12,22 @@ module Network.HTTP.Affjax
   , RetryPolicy(..)
   , defaultRetryPolicy
   , retry
+  , module Affjax.ResponseFormat
   ) where
 
 import Prelude
 
+import Affjax.RequestBody as RequestBody
+import Affjax.RequestHeader (RequestHeader(..), requestHeaderName, requestHeaderValue)
+import Affjax.ResponseFormat (ResponseFormatError(..), printResponseFormatError)
+import Affjax.ResponseFormat as ResponseFormat
+import Affjax.ResponseHeader (ResponseHeader, responseHeader)
+import Affjax.StatusCode (StatusCode(..))
 import Control.Monad.Except (runExcept, throwError)
 import Control.Parallel (parOneOf)
 import Data.Argonaut.Core (Json)
 import Data.Argonaut.Core as J
 import Data.Argonaut.Parser (jsonParser)
-import Data.Array (intercalate)
 import Data.Array as Arr
 import Data.Either (Either(..), either)
 import Data.Foldable (any)
@@ -31,6 +37,7 @@ import Data.Function.Uncurried (Fn2, runFn2)
 import Data.HTTP.Method (Method(..), CustomMethod)
 import Data.HTTP.Method as Method
 import Data.Int (toNumber)
+import Data.List.NonEmpty as NEL
 import Data.Maybe (Maybe(..))
 import Data.Nullable (Nullable, toNullable)
 import Data.Time.Duration (Milliseconds(..))
@@ -39,13 +46,8 @@ import Effect.Aff.Compat as AC
 import Effect.Class (liftEffect)
 import Effect.Exception (Error, error)
 import Effect.Ref as Ref
-import Foreign (F, Foreign, ForeignError(..), fail, renderForeignError, unsafeReadTagged, unsafeToForeign)
+import Foreign (F, Foreign, ForeignError(..), fail, unsafeReadTagged, unsafeToForeign)
 import Math as Math
-import Network.HTTP.Affjax.RequestBody as RequestBody
-import Network.HTTP.Affjax.ResponseFormat as ResponseFormat
-import Network.HTTP.RequestHeader (RequestHeader(..), requestHeaderName, requestHeaderValue)
-import Network.HTTP.ResponseHeader (ResponseHeader, responseHeader)
-import Network.HTTP.StatusCode (StatusCode(..))
 
 -- | A record that contains all the information to perform an HTTP request.
 -- | Instead of constructing the record from scratch it is often easier to build
@@ -87,77 +89,77 @@ type Response a =
   { status :: StatusCode
   , statusText :: String
   , headers :: Array ResponseHeader
-  , response :: a
+  , body :: a
   }
 
 -- | Type alias for URL strings to aid readability of types.
 type URL = String
 
 -- | Makes a `GET` request to the specified URL.
-get :: forall a. ResponseFormat.ResponseFormat a -> URL -> Aff (Response a)
+get :: forall a. ResponseFormat.ResponseFormat a -> URL -> Aff (Response (Either ResponseFormatError a))
 get rt u = request rt $ defaultRequest { url = u }
 
 -- | Makes a `POST` request to the specified URL, sending data.
-post :: forall a. ResponseFormat.ResponseFormat a -> URL -> RequestBody.RequestBody -> Aff (Response a)
+post :: forall a. ResponseFormat.ResponseFormat a -> URL -> RequestBody.RequestBody -> Aff (Response (Either ResponseFormatError a))
 post rt u c = request rt $ defaultRequest { method = Left POST, url = u, content = Just c }
 
 -- | Makes a `POST` request to the specified URL with the option to send data.
-post' :: forall a. ResponseFormat.ResponseFormat a -> URL -> Maybe RequestBody.RequestBody -> Aff (Response a)
+post' :: forall a. ResponseFormat.ResponseFormat a -> URL -> Maybe RequestBody.RequestBody -> Aff (Response (Either ResponseFormatError a))
 post' rt u c = request rt $ defaultRequest { method = Left POST, url = u, content = c }
 
 -- | Makes a `POST` request to the specified URL, sending data and ignoring the
 -- | response.
 post_ :: URL -> RequestBody.RequestBody -> Aff (Response Unit)
-post_ = post ResponseFormat.ignore
+post_ url = map (_ { body = unit }) <<< post ResponseFormat.ignore url
 
 -- | Makes a `POST` request to the specified URL with the option to send data,
 -- | and ignores the response.
 post_' :: URL -> Maybe RequestBody.RequestBody -> Aff (Response Unit)
-post_' = post' ResponseFormat.ignore
+post_' url = map (_ { body = unit }) <<< post' ResponseFormat.ignore url
 
 -- | Makes a `PUT` request to the specified URL, sending data.
-put :: forall a. ResponseFormat.ResponseFormat a -> URL -> RequestBody.RequestBody -> Aff (Response a)
+put :: forall a. ResponseFormat.ResponseFormat a -> URL -> RequestBody.RequestBody -> Aff (Response (Either ResponseFormatError a))
 put rt u c = request rt $ defaultRequest { method = Left PUT, url = u, content = Just c }
 
 -- | Makes a `PUT` request to the specified URL with the option to send data.
-put' :: forall a. ResponseFormat.ResponseFormat a -> URL -> Maybe RequestBody.RequestBody -> Aff (Response a)
+put' :: forall a. ResponseFormat.ResponseFormat a -> URL -> Maybe RequestBody.RequestBody -> Aff (Response (Either ResponseFormatError a))
 put' rt u c = request rt $ defaultRequest { method = Left PUT, url = u, content = c }
 
 -- | Makes a `PUT` request to the specified URL, sending data and ignoring the
 -- | response.
 put_ :: URL -> RequestBody.RequestBody -> Aff (Response Unit)
-put_ = put  ResponseFormat.ignore
+put_ url = map (_ { body = unit }) <<< put ResponseFormat.ignore url
 
 -- | Makes a `PUT` request to the specified URL with the option to send data,
 -- | and ignores the response.
 put_' :: URL -> Maybe RequestBody.RequestBody -> Aff (Response Unit)
-put_' = put'  ResponseFormat.ignore
+put_' url = map (_ { body = unit }) <<< put' ResponseFormat.ignore url
 
 -- | Makes a `DELETE` request to the specified URL.
-delete :: forall a. ResponseFormat.ResponseFormat a -> URL -> Aff (Response a)
+delete :: forall a. ResponseFormat.ResponseFormat a -> URL -> Aff (Response (Either ResponseFormatError a))
 delete rt u = request rt $ defaultRequest { method = Left DELETE, url = u }
 
 -- | Makes a `DELETE` request to the specified URL and ignores the response.
 delete_ :: URL -> Aff (Response Unit)
-delete_ = delete ResponseFormat.ignore
+delete_ = map (_ { body = unit }) <<< delete ResponseFormat.ignore
 
 -- | Makes a `PATCH` request to the specified URL, sending data.
-patch :: forall a. ResponseFormat.ResponseFormat a -> URL -> RequestBody.RequestBody -> Aff (Response a)
+patch :: forall a. ResponseFormat.ResponseFormat a -> URL -> RequestBody.RequestBody -> Aff (Response (Either ResponseFormatError a))
 patch rt u c = request rt $ defaultRequest { method = Left PATCH, url = u, content = Just c }
 
 -- | Makes a `PATCH` request to the specified URL with the option to send data.
-patch' :: forall a. ResponseFormat.ResponseFormat a -> URL -> Maybe RequestBody.RequestBody -> Aff (Response a)
+patch' :: forall a. ResponseFormat.ResponseFormat a -> URL -> Maybe RequestBody.RequestBody -> Aff (Response (Either ResponseFormatError a))
 patch' rt u c = request rt $ defaultRequest { method = Left PATCH, url = u, content = c }
 
 -- | Makes a `PATCH` request to the specified URL, sending data and ignoring the
 -- | response.
 patch_ :: URL -> RequestBody.RequestBody -> Aff (Response Unit)
-patch_ = patch ResponseFormat.ignore
+patch_ url = map (_ { body = unit }) <<< patch ResponseFormat.ignore url
 
 -- | Makes a `PATCH` request to the specified URL with the option to send data,
 -- | and ignores the response.
 patch_' :: URL -> Maybe RequestBody.RequestBody -> Aff (Response Unit)
-patch_' = patch' ResponseFormat.ignore
+patch_' url = map (_ { body = unit }) <<< patch' ResponseFormat.ignore url
 
 -- | A sequence of retry delays, in milliseconds.
 type RetryDelayCurve = Int -> Milliseconds
@@ -236,12 +238,14 @@ retry policy run req = do
 -- | ```purescript
 -- | get json "/resource"
 -- | ```
-request :: forall a. ResponseFormat.ResponseFormat a -> RequestOptions -> Aff (Response a)
+request :: forall a. ResponseFormat.ResponseFormat a -> RequestOptions -> Aff (Response (Either ResponseFormatError a))
 request rt req = do
   res <- AC.fromEffectFnAff $ runFn2 _ajax responseHeader req'
-  case runExcept (fromResponse' res.response) of
-    Left err -> throwError $ error $ intercalate "\n" (map renderForeignError err)
-    Right res' -> pure (res { response = res' })
+  case runExcept (fromResponse' res.body) of
+    Left err -> do
+      pure (res { body = Left (ResponseFormatError (NEL.head err) res.body) })
+    Right res' -> do
+      pure (res { body = Right res' })
   where
 
   req' :: AjaxRequest a

src/Network/HTTP/Affjax/RequestBody.purs renamed to src/Affjax/RequestBody.purs

@@ -1,4 +1,4 @@
-module Network.HTTP.Affjax.RequestBody where
+module Affjax.RequestBody where
 
 import Data.Argonaut.Core (Json)
 import Data.ArrayBuffer.Types as A

src/Network/HTTP/RequestHeader.purs renamed to src/Affjax/RequestHeader.purs

@@ -1,4 +1,4 @@
-module Network.HTTP.RequestHeader where
+module Affjax.RequestHeader where
 
 import Prelude
 

src/Network/HTTP/Affjax/ResponseFormat.purs renamed to src/Affjax/ResponseFormat.purs

@@ -1,4 +1,4 @@
-module Network.HTTP.Affjax.ResponseFormat where
+module Affjax.ResponseFormat where
 
 import Prelude
 
@@ -7,6 +7,8 @@ import Data.ArrayBuffer.Types (ArrayBuffer)
 import Data.Maybe (Maybe(..))
 import Data.MediaType (MediaType)
 import Data.MediaType.Common (applicationJSON)
+import Foreign (Foreign, ForeignError)
+import Foreign as Foreign
 import Web.DOM.Document (Document)
 import Web.File.Blob (Blob)
 
@@ -54,3 +56,12 @@ toMediaType =
   case _ of
     Json _ -> Just applicationJSON
     _ -> Nothing
+
+-- | Used when an error occurs when attempting to decode into a particular
+-- | response format. The error that occurred when decoding is included, along
+-- | with the value that decoding was attempted on.
+data ResponseFormatError = ResponseFormatError ForeignError Foreign
+
+printResponseFormatError :: ResponseFormatError → String
+printResponseFormatError (ResponseFormatError err _) =
+  Foreign.renderForeignError err

src/Network/HTTP/ResponseHeader.purs renamed to src/Affjax/ResponseHeader.purs

@@ -1,4 +1,4 @@
-module Network.HTTP.ResponseHeader
+module Affjax.ResponseHeader
   ( ResponseHeader()
   , responseHeader
   , responseHeaderName

src/Network/HTTP/StatusCode.purs renamed to src/Affjax/StatusCode.purs

@@ -1,4 +1,4 @@
-module Network.HTTP.StatusCode where
+module Affjax.StatusCode where
 
 import Prelude
 

test-server.js

@@ -2,23 +2,31 @@ module Test.DocExamples where
 
 import Prelude
 
+import Affjax as AX
+import Affjax.RequestBody as RequestBody
+import Affjax.ResponseFormat as ResponseFormat
 import Data.Argonaut.Core as J
 import Data.Either (Either(..))
 import Data.HTTP.Method (Method(..))
+import Effect (Effect)
 import Effect.Aff (launchAff)
-import Effect.Class (liftEffect)
-import Effect.Console (log)
-import Network.HTTP.Affjax as AX
-import Network.HTTP.Affjax.RequestBody as RequestBody
-import Network.HTTP.Affjax.ResponseFormat as ResponseFormat
+import Effect.Class.Console (log)
 
-main = launchAff $ do
+main :: Effect Unit
+main = void $ launchAff $ do
   res <- AX.request ResponseFormat.json (AX.defaultRequest { url = "/api", method = Left GET })
-  liftEffect $ log $ "GET /api response: " <> J.stringify res.response
+  case res.body of
+    Left err -> log $ "GET /api response failed to decode: " <> AX.printResponseFormatError err
+    Right json -> log $ "GET /api response: " <> J.stringify json
 
-main' = launchAff $ do
+main' :: Effect Unit
+main' = void $ launchAff $ do
   res1 <- AX.get ResponseFormat.json "/api"
-  liftEffect $ log $ "GET /api response: " <> J.stringify res1.response
+  case res1.body of
+    Left err -> log $ "GET /api response failed to decode: " <> AX.printResponseFormatError err
+    Right json -> log $ "GET /api response: " <> J.stringify json
 
   res2 <- AX.post ResponseFormat.json "/api" (RequestBody.json (J.fromString "test"))
-  liftEffect $ log $ "POST /api response: " <> J.stringify res2.response
+  case res2.body of
+    Left err -> log $ "POST /api response failed to decode: " <> AX.printResponseFormatError err
+    Right json -> log $ "POST /api response: " <> J.stringify json