Given an encoding and a Buffer, returns a Future of the result of
encoding said buffer using the given encoding. The Future will reject
with an Error if the encoding is unknown.
Given a Buffer, returns a Future of a Readable stream which will
emit the given Buffer before ending.
The stream is wrapped in a Future because creation of a stream causes
side-effects if it's not consumed in time, making it safer to pass it
around wrapped in a Future.
Resolves a Future with the given value in the next tick,
using process.nextTick. The scheduled job cannot be
cancelled and will run before any other jobs, effectively
blocking the event loop until it's completed.
Resolves a Future with the given value in the next tick,
using setImmediate. This job will run as soon as all
other jobs are completed. When the Future is cancelled, the
job is unscheduled.
> immediate ('results')Future.of ('results')
Http
The functions below are to be used in compositions such as the one shown
below, in order to cover a wide variety of HTTP-related use cases.
import {reject, map, chain, encase, fork} from 'fluture';import {retrieve, matchStatus, followRedirects, autoBufferResponse, responseToError} from 'fluture-node';const json = res => ( chain (encase (JSON.parse)) (autoBufferResponse (res)));const notFound = res => ( chain (({message}) => reject (new Error (message))) (json (res)));retrieve ('https://api.github.com/users/Avaq') ({'User-Agent': 'Avaq'})
The example above will either:
log "Aldwin Vlasblom" to the terminal if nothing weird happens; or
Report a 404 error using the message returned from the server; or
How an unexpected status was treated: We passed in a handler to
matchStatus.
We used responseToError, conviently provided by
this library, but we could have used a custom mechanism.
How responses with expected status codes are treated:
The matchStatus function lets us provide a handler
based on the status code of the response. Each handler has full control
over the response.
How the response body is buffered and decoded: Our json function uses
autoBufferResponse to buffer and decode the
response according to the mime type provided in the headers. However, we
could have used lower level functions, such as
or even just .
The goal is to give you as much control over HTTP requests and responses
as possible, while still keeping boilerplate low by leveraging function
composition.
This contrasts with many of the popular HTTP client libraries out there,
which either make decisions for you, taking away control in an attempt to
provide a smoother usage experience, or which take complicated structures
of interacting options to attempt to cater to as many cases as possible.
Constructs a value of type Request to be used as an argument for
functions such as sendRequest.
Takes the following arguments:
An Object containing any http options except: auth, host,
hostname, path, port, and protocol; because they are part of
the URL, and signal; because Fluture handles the cancellation.
A String containing the request URL.
A Future of a Readable stream of Buffers to be used as the
request body. Note that the Future must produce a brand new Stream
every time it is forked, or if it can't, it is expected to reject
with a value of type Error.
This is the "lowest level" function for making HTTP requests. It does not
handle buffering, encoding, content negotiation, or anything really.
For most use cases, you can use one of the more specialized functions:
Given a Request, returns a Future which makes an HTTP request
and resolves with the resulting Response.
If the Future is cancelled, the request is aborted.
Given a MIME type, a request method, a URL, a StrMap of headers, and
finally a Buffer, returns a Future which will send the Buffer to the
server at the given URL using the given request method, telling it the
buffer contains data of the given MIME type.
This function will always send the Content-Type and Content-Length headers,
alongside the provided headers. Manually provoding either of these headers
override those generated by this function.
Given a request method, a URL, a StrMap of headers and a JavaScript plain
object, returns a Future which sends the object to the server at the
given URL after JSON-encoding it.
A version of send specialized in sending form data.
Given a request method, a URL, a StrMap of headers and a JavaScript plain
object, returns a Future which sends the object to the server at the
given URL after www-form-urlencoding it.
This is kind of like a switch statement on the status code of the
Response message. Or, if you will, a pattern match against the
Response type if you imagine it being tagged via the status code.
The first argument is the "default" case, and the second argument is a
map of status codes to functions that should have the same type as the
first argument.
The resulting function Response -> a has the same signature as the input
functions, meaning you can use matchStatusagain to "extend" the
pattern by passing the old pattern as the "default" case for the new one:
import {reject} from 'fluture';matchStatus (processResponse) ({ 404: () => reject (new Error ('Example not found!')),});
A redirection strategy that simply reissues the original Request to the
Location specified in the given Response, but only if the original request
was using the GET method.
If the new location is on an external host, then any confidential headers
(such as the cookie header) will be dropped from the new request.
A redirection strategy that sends a new GET request based on the original
request to the Location specified in the given Response. If the response
does not contain a valid location, the request is not redirected.
The original request method and body are discarded, but other options
are preserved. If the new location is on an external host, then any
confidential headers (such as the cookie header) will be dropped from the
new request.
A redirection strategy that removes any caching headers if present and
retries the request, or does nothing if no caching headers were present
on the original request.
Redirections with status codes 301, 302, and 307 are only followed if the
original request used the GET method, and redirects with status code 304
are left alone for a caching layer to deal with.
This redirection policy is used by default in the
followRedirects function. You can extend it, using
matchStatus to create a custom redirection policy, as
shown in the example:
Aggressively follows redirects in mild violation of
RFC2616 Section 10.3. In particular, anywhere that a redirection
should be interrupted for user confirmation or caching, this policy
follows the redirection nonetheless.
Redirections with status codes 301, 302, and 307 are always followed
without user intervention, and redirects with status code 304 are
retried without conditions if the original request had any conditional
headers.
Given a function that take a Response and produces a new Request, and a
"maximum" number, recursively keeps resolving new requests until a request
is encountered that was seen before, or the maximum number is reached.
This function "tags" a Response based on a given status code.
If the response status matches the given status code, the returned Future
will resolve. If it doesn't, the returned Future will reject.
See also matchStatus, which will probably be more useful
in most cases.
The idea is that you can compose this function with one that returns a
Response, and reject any responses that don't meet the expected status
code.
In combination with responseToError, you can then
flatten it back into the outer Future. The usage example under the
Http section shows this.
Given an IncomingMessage, buffers and decodes the message body using the
charset provided in the message headers. Falls back to UTF-8 if the
charset was not provided.
Returns a Future with the buffered, encoded, message body.
How the response body is parsed: We used Fluture.encase with
JSON.parse to parse JSON with a safe failure path. However, we
could have used a more refined approach to parsing the JSON, for
example by using S.parseJson.