# es6-request > HTTP Request library written in ES6 for Node.js Latest version **3.0.5** (published 2019-06-11) · MIT license · 0 weekly downloads ## Install ```sh npm install es6-request pnpm add es6-request yarn add es6-request bun add es6-request ``` ## Health **Score 20/100 (F)** — status: abandoned. Positive: has types; no vulnerabilities. Warnings: low downloads; no esm support. Negative: abandoned; low maintenance score. ## Facts | | | |---|---| | Version | 3.0.5 | | Published | 2019-06-11 | | First published | 2016-03-24 | | Weekly downloads | 0 | | License | MIT | | TypeScript types | bundled | | Module format | CommonJS | | Node | >=8.0.0 | | Dependencies | 0 | | Unpacked size | 69.4 KB | | Known vulnerabilities | 0 | | Install scripts | no | | GitHub stars | 5 | | Author | alexrsagen | | Maintainers | alexrsagen | | Keywords | request, es6, http, https, multipart | ## Links - npm: https://www.npmjs.com/package/es6-request - Repository: https://github.com/alexrsagen/node-es6-request - Homepage: https://github.com/alexrsagen/node-es6-request#readme - Issues: https://github.com/alexrsagen/node-es6-request/issues - npm.io page: https://npm.io/package/es6-request ## 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 - 3.0.5 (latest) — 2019-06-11 - 3.0.4 — 2019-03-03 - 3.0.3 — 2019-02-04 - 3.0.2 — 2019-02-01 - 3.0.1 — 2019-02-01 - 3.0.0 — 2019-01-31 - 2.4.0 — 2018-04-20 - 2.3.9 — 2018-03-29 - 2.3.8 — 2018-03-12 - 2.3.7 — 2017-07-20 - 2.3.5 — 2017-07-18 - 2.3.4 — 2017-07-18 - 2.3.3 — 2017-07-18 - 2.3.2 — 2017-07-18 - 2.3.1 — 2017-07-18 - … 28 more at https://npm.io/package/es6-request/versions ## README # node-es6-request HTTP Request library written in ES6 for Node.js. Now with TypeScript definitions! **Warning! Only supports Node.js >=8.0.0** (See "Added in" [here](https://nodejs.org/api/stream.html#stream_writable_destroy_error)) ## Installation ``` npm i es6-request ``` ## API Functions that return a new `Request` instance: * `es6-request`.get(`url`) * `es6-request`.put(`url`) * `es6-request`.post(`url`) * `es6-request`.head(`url`) * `es6-request`.patch(`url`) * `es6-request`.delete(`url`) * `es6-request`.options(`url`) ##### `Request` ##### `Request`.query(`key`, `value`) Alternatively, **`Request`.query(`object`)** * `key` [<string>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type) Query string key * `value` <any> Query string value * `object` [<Object>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object) Query string key/value object This function adds to the query string of the `url` or creates a new query string that will be added to the `url` before performing the reuqest. Returns `Request` ##### `Request`.header(`key`, `value`) Alternatively, **`Request`.headers(`object`)** * `key` [<string>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type) Header name * `value` <any> Header value * `object` [<Object>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object) Header key/value object Adds a header to the request by the name of `key` and the content of `val` or adds the key/value headers from `object`. Returns `Request` ##### `Request`.authBasic(`username`, `password`) * `username` [<string>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type) Username * `password` [<string>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type) Password Adds an `Authorization: Basic ` header to your request. Returns `Request` ##### `Request`.authBearer(`bearer`) * `bearer` [<string>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type) Bearer token Adds an `Authorization: Bearer ` header to your request. Adds options from a key/value object to the Node.js HTTP [options](https://nodejs.org/api/http.html#http_new_agent_options). Returns `Request` ##### `Request`.option(`key`, `value`) Alternatively, **`Request`.options(`object`)** * `key` [<string>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type) Option name * `value` <any> Option value * `object` [<Object>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object) Option key/value object Adds an option or a key/value object of options to the Node.js HTTP [options](https://nodejs.org/api/http.html#http_new_agent_options). Returns `Request` ##### `Request`.sendForm(`form`) * `form` [<Object>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object) Form key/value object Transforms the `form` object into a querystring and sends the request as `application/x-www-form-urlencoded`. Returns a [<Promise>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) ##### `Request`.sendMultipart([`form`][, `files`][, `filesFieldNameFormat`][, `encoding`]) * `form` [<Object>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object) Form key/value object (field name/contents) * `files` [<Object>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object) Files key/value object (filename/contents) * `filesFieldNameFormat`[<string>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type) Multipart file field name (defaults to `files[%i]`) * `encoding` [<string>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type) Multipart entity Content-Transfer-Encoding (defaults to `utf8`) Transforms the `form` and `files` into multipart form fields and sends the request as `multipart/form-data`. Returns a [<Promise>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) ##### `Request`.sendJSON(`data`) * `data` <any> Data that will be transformed into JSON Transforms the `data` into a JSON string and sends the request as `application/json`. Returns a [<Promise>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) ##### `Request`.write(`chunk`[, `encoding`][, `callback`]) * `chunk` [<string>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type) | [<Buffer>](https://nodejs.org/api/buffer.html#buffer_class_buffer) * `encoding` [<string>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type) * `callback` [<Function>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function) You must run `Request`.start() before running this function. Directly writes to the request using [this](https://nodejs.org/api/http.html#http_request_write_chunk_encoding_callback) function from Node.js. Returns `Request` ##### `Request`.send(`chunk`[, `encoding`][, `callback`]) * `chunk` [<string>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type) | [<Buffer>](https://nodejs.org/api/buffer.html#buffer_class_buffer) * `encoding` [<string>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type) * `callback` [<Function>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function) Starts a request, then directly writes to the it using [this](https://nodejs.org/api/http.html#http_request_write_chunk_encoding_callback) function from Node.js, then performs the request. Returns a [<Promise>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) ##### `Request`.start() Starts a request. After this function has been called, helper functions like `Request`.headers(), `Request`.header() and `Request`.query() will no longer work until the request has ended. Returns `Request` ##### `Request`.pipe(`destination`) Starts the request if it is not already started. Pipes the response chunks to the destination stream using [this](https://nodejs.org/api/stream.html#stream_readable_pipe_destination_options) function from Node.js, then performs the request. Returns `Request` ##### `Request`.perform() This function ends a request. It is called by other functions like [Request.send()](#requestsend) and [Request.pipe()](#requestpipe). Returns a [<Promise>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) ## Usage #### Simple GET Request ```javascript const request = require("es6-request"); // you can exchange "get" with "head", "delete" or "options" here // they all have the exact same API request.get("https://raw.githubusercontent.com/alexrsagen/node-es6-request/master/README.md") .then(([body, res]) => { console.log(body); // should output this README file! }); ``` #### POST Request The following example will send a x-www-form-urlencoded request to the server containing keys and values from the json object. ```javascript const request = require("es6-request"); // you can exchange "post" with either "put" or "patch" here // they all have the exact same API request.post("http://api.somewebsite.com/endpoint") .sendForm({ somekey: "somevalue" }) .then(([body, res]) => { // ... }); ``` This example will send a raw string to the server. ```javascript const request = require("es6-request"); // you can exchange "post" with either "put" or "patch" here // they all have the exact same API request.post("http://api.somewebsite.com/endpoint") .send("i am a string, i will be sent to the server with a POST request.") .then(([body, res]) => { // ... }); ``` #### Query string This works the same way with any other request type. ```javascript const request = require("es6-request"); // sends a GET request to http://api.somewebsite.com/endpoint?this=that&one=two&three=four request.get("http://api.somewebsite.com/endpoint") .query("this", "that") .query({ "one": "two", "three": "four" }) .then(([body, res]) => { // ... }); ``` #### Headers ```javascript const request = require("es6-request"); // Sends a GET request with these headers: // { // "Accept": "application/json", // "Header-Name": "header value", // "Another-Header": "another value" // } request.get("http://api.somewebsite.com/endpoint"); .header("Accept", "application/json") .headers({ "Header-Name": "header value", "Another-Header": "another value" }) .then(([body, res]) => { console.log(res.headers); // ... }); ``` #### Pipes The following example POSTs all data you enter to STDIN to the local server we create, which then logs the data back to the console. ```javascript const request = require("es6-request"); const server = require("http").createServer((req, res) => { req.setEncoding('utf8'); req.on('data', (chunk) => { console.log(chunk); }); req.on('end', () => { res.end(); }); }).listen(1337); process.stdin.pipe(request.post("http://localhost:1337")); ``` This example pipes the GitHub logo to a file named `logo.png`. ```javascript const request = require("es6-request"); const fs = require("fs"); request.get("https://github.com/images/modules/logos_page/GitHub-Mark.png").pipe(fs.createWriteStream("logo.png")).perform(); ``` #### Multipart forms The following example POSTs a field and a file to a server using `multipart/form-data` ```javascript const request = require("es6-request"); const fs = require("es6-fs"); fs.readFile("logo.png") .then(contents => request.post("http://api.somewebsite.com/endpoint") .sendMultipart({ somekey: "somevalue" }, { "logo.png": contents }, "files[%i]", "base64") ); ``` Sample multipart form body that gets sent to the server: ``` ----------------------------151a08730e1f MIME-Version: 1.0 Content-Transfer-Encoding: base64 Content-Disposition: form-data; name="somekey" c29tZXZhbHVl ----------------------------151a08730e1f MIME-Version: 1.0 Content-Transfer-Encoding: base64 Content-Disposition: form-data; name="files[0]"; filename="logo.png" iVBORw0KGgoAAAA(trimmed 19073 characters...) ----------------------------151a08730e1f-- ``` --- _Source: https://npm.io/package/es6-request · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._