fluture-node
Advanced tools
FP-style HTTP and streaming utils for Node based on Fluture.
Skip to the Http section for the main code example.
$ npm install --save fluture fluture-node
On Node 12 and up, this module can be loaded directly with import or
require. On Node versions below 12, require or the esm-loader can
be used.
once :: String -> EventEmitter -> Future Error aResolve a Future with the first event emitted over the given event emitter under the given event name.
When the Future is cancelled, it removes any trace of itself from the event emitter.
> const emitter = new EventEmitter ();
> setTimeout (() => emitter.emit ('answer', 42), 100);
> once ('answer') (emitter);
Future.of (42);
encode :: Charset -> Buffer -> Future Error StringGiven 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.
> encode ('utf8') (Buffer.from ('Hello world!'));
'Hello world!'
streamOf :: Buffer -> Future a (Readable Buffer)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.
emptyStream :: Future a (Readable Buffer)A Readable stream which ends after emiting zero bytes. Can be useful
as an empty Request body, for example.
buffer :: Readable a -> Future Error (Array a)Buffer all data on a Readable stream into a Future of an Array.
When the Future is cancelled, it removes any trace of itself from the Stream.
> const stream = new Readable ({read: () => {}});
> setTimeout (() => {
. stream.push ('hello');
. stream.push ('world');
. stream.push (null);
. }, 100);
> buffer (stream);
Future.of ([Buffer.from ('hello'), Buffer.from ('world')]);
bufferString :: Charset -> Readable Buffer -> Future Error StringA version of buffer specialized in Strings.
Takes a charset and a Readable stream of Buffers, and returns a Future containing a String with the fully buffered and encoded result.
instant :: b -> Future a bResolves 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.
> instant ('noodles')
Future.of ('noodles')
immediate :: b -> Future a bResolves 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')
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'})
.pipe (chain (followRedirects (20)))
.pipe (chain (matchStatus (responseToError) ({200: json, 404: notFound})))
.pipe (map (avaq => avaq.name))
.pipe (fork (console.error) (console.log));
The example above will either:
"Aldwin Vlasblom" to the terminal if nothing weird happens; orNote that we were in control of the following:
How redirects are followed: We use followRedirects
with a maxmum of 20 redirects, but we could have used a different
redirection function using followRedirectsWith
with the aggressiveRedirectionPolicy or
even a fully custom policy.
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
bufferResponse or even just buffer.
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.
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.
Request :: Object -> Url -> Future Error (Readable Buffer) -> RequestConstructs a value of type Request to be used as an argument for
functions such as sendRequest.
Takes the following arguments:
auth, host,
hostname, path, port, and protocol; because they are part of
the URL, and signal; because Fluture handles the cancellation.See sendRequest for a usage example.
Request.options :: Request -> ObjectGet the options out of a Request.
Request.url :: Request -> UrlGet the url out of a Request.
Request.body :: Request -> Future Error (Readable Buffer)Get the body out of a Request.
Response :: Request -> IncomingMessage -> ResponseConstructs a value of type Response. These values are typically created
for you by functions such as sendRequest.
Takes the following arguments:
Response.request :: Response -> RequestGet the request out of a Response.
Response.message :: Response -> IncomingMessageGet the message out of a Response.
sendRequest :: Request -> Future Error ResponseThis 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.
import {attempt} from 'fluture';
import {createReadStream} from 'fs';
const BinaryPostRequest = Request ({
method: 'POST',
headers: {'Transfer-Encoding': 'chunked'},
});
const eventualBody = attempt (() => createReadStream ('./data.bin'));
sendRequest (BinaryPostRequest ('https://example.com') (eventualBody));
If you want to use this function to transfer a stream of data, don't forget to set the Transfer-Encoding header to "chunked".
retrieve :: Url -> StrMap String -> Future Error ResponseA version of sendRequest specialized in the GET method.
Given a URL and a StrMap of request headers, returns a Future which makes a GET requests to the given resource.
retrieve ('https://api.github.com/users/Avaq') ({'User-Agent': 'Avaq'})
send :: Mimetype -> Method -> Url -> StrMap String -> Buffer -> Future Error ResponseA version of sendRequest for sending arbitrary data to
a server. There's also more specific versions for sending common types of
data:
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.
sendJson :: Method -> String -> StrMap String -> JsonValue -> Future Error ResponseA version of send specialized in sending JSON.
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.
sendJson ('PUT')
('https://example.com/users/bob')
({Authorization: 'Bearer asd123'})
({name: 'Bob', email: 'bob@example.com'});
sendForm :: Method -> String -> StrMap String -> JsonValue -> Future Error ResponseA 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.
sendForm ('POST')
('https://example.com/users/create')
({})
({name: 'Bob', email: 'bob@example.com'});
matchStatus :: (Response -> a) -> StrMap (Response -> a) -> Response -> aTransform a Response based on its status code.
import {chain} from 'fluture';
const processResponse = matchStatus (responseToError) ({
200: autoBufferResponse,
});
chain (processResponse) (retreive ('https://example.com'));
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 matchStatus again 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!')),
});
redirectAnyRequest :: Response -> RequestA redirection strategy that simply reissues the original Request to the Location specified in the given Response.
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.
Used in the defaultRedirectionPolicy and
the aggressiveRedirectionPolicy.
redirectIfGetMethod :: Response -> RequestA 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.
Used in followRedirectsStrict.
redirectUsingGetMethod :: Response -> RequestA 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.
Used in the defaultRedirectionPolicy and
the aggressiveRedirectionPolicy.
retryWithoutCondition :: Response -> RequestA 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.
Used in the defaultRedirectionPolicy.
defaultRedirectionPolicy :: Response -> RequestCarefully follows redirects in strict accordance with RFC2616 Section 10.3.
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:
See also aggressiveRedirectionPolicy.
const redirectToBestOption = () => {
// Somehow figure out which URL to redirect to.
};
const myRedirectionPolicy = matchStatus (defaultRedirectionPolicy) ({
300: redirectToBestOption,
301: redirectUsingGetMethod,
});
retrieve ('https://example.com') ({})
.pipe (chain (followRedirectsWith (myRedirectionPolicy) (10)))
aggressiveRedirectionPolicy :: Response -> RequestAggressively 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.
See also defaultRedirectionPolicy.
retrieve ('https://example.com') ({})
.pipe (chain (followRedirectsWith (aggressiveRedirectionPolicy) (10)))
followRedirectsWith :: (Response -> Request) -> Number -> Response -> Future Error ResponseGiven 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.
See followRedirects for an out-of-the-box redirect-
follower. See aggressiveRedirectionPolicy
and defaultRedirectionPolicy for
additional usage examples.
followRedirects :: Number -> Response -> Future Error ResponseGiven the maximum numbers of redirections, follows redirects according to the default redirection policy.
See the Http section for a usage example.
acceptStatus :: Number -> Response -> Future Response ResponseThis 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.
bufferMessage :: Charset -> IncomingMessage -> Future Error StringA version of buffer specialized in IncomingMessages.
See also bufferResponse and
autoBufferMessage.
Given a charset and an IncomingMessage, returns a Future with the buffered, encoded, message body.
bufferResponse :: Charset -> Response -> Future Error StringA composition of Response.message and
bufferMessage for your convenience.
See also autoBufferResponse.
autoBufferMessage :: IncomingMessage -> Future Error StringGiven 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.
See also bufferMessage.
autoBufferResponse :: Response -> Future Error StringA composition of Response.message and
autoBufferMessage for your convenience.
See also bufferResponse.
responseToError :: Response -> Future Error aGiven a Response, returns a rejected Future of an instance of Error with a message based on the content of the response.
FAQs
FP-style HTTP and streaming utils for Node based on Fluture
The npm package fluture-node receives a total of 7 weekly downloads. As such, fluture-node popularity was classified as not popular.
We found that fluture-node demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 3 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Research
Socket researchers have discovered malicious npm packages targeting crypto developers, stealing credentials and wallet data using spyware delivered through typosquats of popular cryptographic libraries.
Security News
Socket's package search now displays weekly downloads for npm packages, helping developers quickly assess popularity and make more informed decisions.
Security News
A Stanford study reveals 9.5% of engineers contribute almost nothing, costing tech $90B annually, with remote work fueling the rise of "ghost engineers."