ftch :: Secure, extensible fetching with telemetry
ftch is a Node.js library for doing HTTP requests, focusing on:
Request URLs are often constructed dynamically. To mitigate risk of command-injection attacks, ftch uses URL templates with automatic URL-encoding.
ftch's extensibility mechanism helps minimize boilerplate.
// declare boilerplate here...const api = fetch;// elsewhere...;
ftch allows optionally passing in an EventEmitter to collect in-flight telemetry for each request.
// log the progress of every completed requestconst telemetry = ;telemetry;const api = fetch;
fetch(urlTemplate, params, options)
Makes an HTTP(S) request and returns a promise. By default the returned promise resolves to a Node.js response stream, AKA an http.IncomingMessage. Optionally, it can be made to resolve directly to a buffer, string, or JSON object. Arguments are described below.
Optional URL template string. If provided, it will be a URL pattern capturing zero or more named variables, for example
:version. URL patterns may optionally include scheme, host and port, but named variables may only exist in the path portion of the URL. Examples:
At request time, it's executed against the
params argument, described below. Note that if params declared in the URL template don't have matching values in the
params object, the unexpanded params will be passed through silently to the server. You may opt into stricter behavior by passing
requireExpanded: true in
Optional params object. If
urlTemplate (described above) contains any free variables, this argument must be an object whose properties match all those variables. Values are coerced to strings and URL-encoded.
undefined are treated as empty strings.
All options are optional, and the overall
options object is also optional. Here are the available options:
- headers: Object containing HTTP headers.
- body: The request body. Either a buffer, string, object, or readable stream.
- as: The type of thing you want the promise to resolve to. Allowed values include
- followRedirects: If true, redirects will be followed. Defaults to
- successOnly: If true, reject the promise for all but 2xx range response status codes (after redirects are followed). Default to
- method: HTTP method to use. Defaults to
- query: An object containing query string params that will be added to the request URL. If the request URL already contains a query string, these will be merged in.
- requireExpanded: If truthy, every
urlTemplateis required to have a matching value in the
paramsobject. By default, unexpanded params are silently passed through.
- telemetry: A node EventEmitter object which you provide. ftch will emit events on this object for the progress and timing of the request. It's then your responsibility to listen for events on this object.
fetch.extend(urlTemplate, params, options)
Returns a function with extended defaults. Consider these scenarios:
const parent = ;// scenario 1;// scenario 2const child = parent;// scenario 3;
parent is called in scenario 1, the given
(url, params, opts) is merged into a set of global defaults, using the merge algorithm described below. The result is used to make the request and then discarded.
parent.extend is called in scenario 2, the given
(url, params, opts) is merged into the above-mentioned set of global defaults, using the above-mentioned merge algorithm. The result is not discarded, but rather becomes defaults for subsequent calls on
child is called in scenario 3, the given
(url, params, opts) is merged into the above-mentioned child defaults. The result is used to make the request and then discarded.
The chain continues as
extend is called on subsequent children.
The Merge Algorithm
urlTemplate1 <= urlTemplate2
Since URL templates are valid URLs, node's URL resolution algorithm is used here:
const mergedUrl = url;
params1 <= params2
const mergedParams = Object;
options1 <= options2
Options merge using one of three strategies:
- overwrite: next replaces prev.
- object-assign: Object assign prev <= next.
- array-push: next is pushed onto an array containing all prev values.
Here's how each option gets merged:
- headers: object-assign
- body: overwrite
- as: overwrite
- followRedirects: overwrite
- successOnly: overwrite
- method: overwrite
- query: object-assign
- telemetry: array-push
Additionally, any of the following properties found on the options object are passed through to the underlying node.js request:
servername. Docs for these can be found here and here. All of these extend using the above-mentioned overwrite strategy.