# @dashkite/mercury > Combinators for HTTP requests. Latest version **0.3.1** (published 2021-09-08) · SEE LICENSE IN LICENSE.md license · 0 weekly downloads ## Install ```sh npm install @dashkite/mercury pnpm add @dashkite/mercury yarn add @dashkite/mercury bun add @dashkite/mercury ``` ## Health **Score 20/100 (F)** — status: abandoned. Positive: esm support; no vulnerabilities. Warnings: low downloads; no types; pre 1.0. Negative: abandoned; low maintenance score. ## Facts | | | |---|---| | Version | 0.3.1 | | Published | 2021-09-08 | | First published | 2020-05-11 | | Weekly downloads | 0 | | License | SEE LICENSE IN LICENSE.md | | TypeScript types | none | | Module format | ESM + CommonJS | | Dependencies | 3 | | Unpacked size | 52.6 KB | | Known vulnerabilities | 0 | | Install scripts | no | | GitHub stars | 0 | | Maintainers | dyoder, freeformflow | | Keywords | http, request, functional, programming, combinator | ## Links - npm: https://www.npmjs.com/package/@dashkite/mercury - Repository: https://github.com/dashkite/mercury - Homepage: https://github.com/dashkite/mercury#readme - Issues: https://github.com/dashkite/mercury/issues - npm.io page: https://npm.io/package/@dashkite/mercury ## Dependencies (3) - [@dashkite/joy](https://npm.io/package/@dashkite/joy.md) ^0.3.11 - [@dashkite/katana](https://npm.io/package/@dashkite/katana.md) ^0.4.8 - [es6-url-template](https://npm.io/package/es6-url-template.md) ^3.0.2 ## Alternatives - [launchdarkly-js-client-sdk](https://npm.io/package/launchdarkly-js-client-sdk.md) — 2.5M weekly downloads - [@elastic/elasticsearch](https://npm.io/package/@elastic/elasticsearch.md) — 2.1M weekly downloads - [@c8y/client](https://npm.io/package/@c8y/client.md) — 15.3K weekly downloads - [@signaldb/maverickjs](https://npm.io/package/@signaldb/maverickjs.md) — 1.7K weekly downloads - [@bbc/http-transport-cache](https://npm.io/package/@bbc/http-transport-cache.md) — 1.2K weekly downloads ## Recent versions - 0.3.1 (latest) — 2021-09-08 - 0.3.0 — 2021-08-04 - 0.2.5 — 2021-08-02 - 0.2.4 — 2021-06-05 - 0.2.3 — 2021-05-21 - 0.2.2 — 2021-04-26 - 0.2.1 — 2021-04-25 - 0.2.0 — 2021-04-24 - 0.1.3 — 2021-02-14 - 0.1.2 — 2020-10-17 - 0.1.1 — 2020-09-11 - 0.1.0 — 2020-08-27 - 0.0.20 — 2020-06-13 - 0.0.19 — 2020-06-13 - 0.0.18 — 2020-06-12 - … 17 more at https://npm.io/package/@dashkite/mercury/versions ## README # Mercury _Combinators for making HTTP requests._ Mercury works a lot like SuperAgent, except via function composition instead of chaining. ```coffee 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: ```coffeescript {entries} = await PublicAPI.search title: "cat" category: "animals" ``` Using composition means Mercury is trivially extensible. For example, [Mercury Sky](https://github.com/dashkite/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. [daisho]: https://github.com/dashkite/katana#daisho-data-structure [Katana]: https://github.com/dashkite/katana ### 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](https://tools.ietf.org/html/rfc6570) 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](https://developer.mozilla.org/en-US/docs/Web/API/Blob). | 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. ```coffeescript 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: ```coffeescript 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: ```coffeescript error.context && error.context.response ``` Undefined if request does not have a corresponding response. #### error.status Convenience for: ```coffeescript error.response && error.response.status ``` Undefined if request does not have a corresponding response. --- _Source: https://npm.io/package/@dashkite/mercury · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._