Mercury
Combinators for making HTTP requests.
Mercury works a lot like SuperAgent, except via function composition instead of chaining.
import * as _ from "@dashkite/joy"
import * as m from "@dashkite/mercury"
PublicAPI =
search:
_.flow [
m.request [
m.url "https://api.publicapis.org/entries"
m.query
m.method "get"
m.headers accept: "application/json"
m.expect.status [ 200 ]
]
m.response [ $.json ]
_.get "json"
]
The result is an async function that we can call to make the request:
{entries} = await PublicAPI.search
title: "cat"
category: "animals"
Using composition means Mercury is trivially extensible. For example, Mercury Sky comes with functions to support Panda Sky-based APIs to construct the request and check the response.
Since these are just functions, we can easily add new features. For example, we could write a simple function that adapts the http
combinators to check the URL against an application cache.
Mercury combinators compose to async functions, which means they can be reused within other compositions. For example, we might create an initialization combinator that we can reuse, to ensure a set of resources is available for subsequent requests. This is harder to do with chaining.
Installation
npm i @dashkite/mercury
Use with your favorite bundler or import directly in the browser.
API
Mercury provides two top-level combinators:
-
request
, which takes an array of combinators to specify the request -
response
, which takes an array of combinators for processing the response
Both combinators take a daisho datastructure that may be manipulated using Katana operators.
The response
combinator returns a promise for an object describing the request and response.
Request Combinators
Request combinators may take an argument or implicitly read from the daisho stack.
Combinator | Arguments | Description |
---|---|---|
base | URL | The base URL, used in conjunction with path to construct the full URL. |
path | URL path | The path of the URL, relative to the base URL. |
template | URL template | The URL template to be expanded to generate the URL. |
parameters | object | The parameters to use to expand the URL template. Not be confused with query . |
url | URL | The ultimate URL of the request. |
query | object | The search parameters to be appended to the URL. |
method | text | The method name (ex: GET, PUT, …) for the request. Will be converted to uppercase for you. |
content | any | The content body of the request. Takes a string or a value, which will be converted into a string using its toString method, except for arrays and objects, which are converted into JSON. |
urlencoded | object | The content body, formatted as a URL encoded form. |
headers | object | The headers of the request. |
accept | text | The accept header. |
media | text | The content-type header. |
authorize | text | The authorization header. |
cache | text | The named CacheStorage object to use in processing the request. |
expires | number (milliseconds) | The expiration for cached responses. |
expect.ok | - | Expect an OK response (200 range). |
expect.status | array | The status codes to expect (that will not throw). |
expect.media | text | The content-type of the response. Use with accept. |
Response Combinators
Combinator | Description |
---|---|
json | The result of parsing the response body as JSON. |
text | The response body as plain text. |
blob | The response body as raw data. |
Combinators from outside of Mercury may use additional properties.
Use Outside The Browser
When using Mercury in Node, you will need to install Fetch and Request globally.
import fetch from "node-fetch"
globalThis.fetch ?= fetch
global.Request ?= fetch.Request
If you want to use the cache
combinator, you will also need to install caches
globally:
import { caches } from 'cache-polyfill'
globalThis.caches ?= caches
Errors
When a Mercury combinator throws an exception, the error will contain additional information, if applicable. If there’s a response, it will contain response
and status
properties. If the request does not yet have a corresponding response, these will be undefined.
error.response
Convenience for:
error.context && error.context.response
Undefined if request does not have a corresponding response.
error.status
Convenience for:
error.response && error.response.status
Undefined if request does not have a corresponding response.