Skip to content

Update readme in light of affjax driver changes #172

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Apr 27, 2022
Merged

Update readme in light of affjax driver changes #172

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
c12b068
Direct users to driver libraries; drop quickstart stuff
JordanMartinez Apr 21, 2022
d7790ad
Add note to module docs in case readme is skipped
JordanMartinez Apr 21, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
61 changes: 3 additions & 58 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,64 +7,9 @@

A library taking advantage of [`aff`](https://github.com/purescript-contrib/purescript-aff) to enable pain-free asynchronous AJAX requests and response handling.

## Installation

Install `affjax` with [Spago](https://github.com/purescript/spago):

```sh
spago install affjax
```

If you are using `affjax` in a Node.js setting you will also need to install an additional NPM dependency:

```
npm install xhr2
```

## Quick start

You can construct requests with the `request` function:

```purescript
module Main where

import Prelude

import Affjax as AX
import Affjax.ResponseFormat as ResponseFormat
import Data.Argonaut.Core (stringify, fromString)
import Data.Either (Either(..))
import Data.HTTP.Method (Method(..))
import Effect.Aff (launchAff)
import Effect.Class.Console (log)

main = void $ launchAff $ do
result <- AX.request (AX.defaultRequest { url = "/api", method = Left GET, responseFormat = ResponseFormat.json })
case result of
Left err -> log $ "GET /api response failed to decode: " <> AX.printError err
Right response -> log $ "GET /api response: " <> stringify response.body
```

(`defaultRequest` is a record value that has all the required fields pre-set for convenient overriding when making a request.)

There are also a number of helpers for common `get`, `post`, `put`, `delete`, and `patch` cases:

```purescript
import Affjax.RequestBody as RequestBody
import Data.Maybe (Maybe(..))
import Effect.Aff (launchAff_)

main = launchAff_ do
result1 <- AX.get ResponseFormat.json "/api"
case result1 of
Left err -> log $ "GET /api response failed to decode: " <> AX.printError err
Right response -> log $ "GET /api response: " <> stringify response.body

result2 <- AX.post ResponseFormat.json "/api" (Just (RequestBody.json (fromString "test")))
case result2 of
Left err -> log $ "POST /api response failed to decode: " <> AX.printError err
Right response -> log $ "POST /api response: " <> stringify response.body
```
This library provides types and common functionality that work across environments (e.g. Node, browser), but **it does not work out-of-box**. Rather, use the environment-specific library instead:
- Browser environment: [`purescript-affjax-web`](https://github.com/purescript-contrib/purescript-affjax-web)
- Node environment: [`purescript-affjax-node`](https://github.com/purescript-contrib/purescript-affjax-node)

## Documentation

Expand Down
10 changes: 10 additions & 0 deletions src/Affjax.purs
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,3 +1,13 @@
-- | Note: this module is not intended to be used by end-users.
-- | Rather, use the environment-specific library instead:
-- | - [`purescript-affjax-node`](https://github.com/purescript-contrib/purescript-affjax-node)
-- | - [`purescript-affjax-web`](https://github.com/purescript-contrib/purescript-affjax-web)
-- |
-- | You should use this module if you are writing a driver for a specific environment.
-- | See this module's source code for more details.
-- If you want to write a driver for an environment, see the comments
-- for the `AffjaxDriver` type and look at the `node` and `web` libraries
-- (linked above) as examples.
module Affjax
( Request
, defaultRequest
Expand Down