TSERSful HTTP Interpreter

Make HTTP requests from your applications in a TSERSful way.

Usage

Installation

npm i --save @tsers/http

Using the interpreter

@tsers/http provides a factory function which can be used to construct the actual interpreter. That factory function takes one optional parameter: baseUrl which will be prepended to the all request urls. If baseUrl is not given, then request URLs are used as they are.

import TSERS from "@tsers/core"
import HTTP from "@tsers/http"
import main from "./YourApp"

TSERS(main, {
  HTTP: HTTP(),               // HTTP.request({url: "/foo"}) uses url "/foo"
  API: HTTP("/my/api/v1")     // API.request({url: "/foo"}) uses url "/my/api/v1/foo"
})

API reference

Signals

HTTP interpreter provides one signal transform function

request :: req$ => res$$

Takes an input stream of request objects and returns a stream of cold response streams associated to the given request objects: one request object produces exactly one response stream. The actual response is superagent's response object.

Request object can have the following params:

Parameter	Explanation	Default value
url [required]	Request url, appended to driver's baseUrl
method [required]	Request method: get, post, put or delete	get
query	Object of request query parameters, docs	{}
send	Payload for POST/PUT request, docs	undefined
headers	Object of request headers (object key = header name)	{}
type	Request content type, docs	json
accept	Accepted response type, docs	undefined
fields	Object of form fields (key = field name) for multipart requests, docs	{}
attachments	Array of multipart request attachments ({name, filename, path} objects), docs	[]
auth	Basic HTTP authentication ({user, password} object)	undefined
cors	Enable CORS	false

In order to get a full control of the underlying superagent, one can pass a function fn :: superagent => req as a request object: the function receives the superagent instance as a parameter and should return a superagent request object without .end() being called.

Examples:

const simpleReq$ = O.just({url: "/api/foo", method: "post", send: {msg: "tsers!"}})
const simpleRes$$ = HTTP.request(simpleReq$)
const simpleRes$ = simpleRes$$.switch()

const advancedReq$ = O.just(agent => {
  const req = agent.get("/api/bar")
    .query({foo: "bar"})
    .query({sortBy: "title"})
    .set("X-Secret", "tsers")
  return req
})
const advancedRes$$ = HTTP.request(advancedReq$)
const advancedRes$ = advancedRes$$.switch()

Output

HTTP interpreter doesn't expect any output signals from the application.

License

MIT