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.