rekwest 3.2.0 → 3.3.0

package/README.md

@@ -1,184 +1,186 @@
-The robust request library that humanity deserves 🌐
----
-This package provides highly likely functional and **easy-to-use** abstraction atop of
-native [http(s).request](https://nodejs.org/api/https.html#https_https_request_url_options_callback)
-and [http2.request](https://nodejs.org/api/http2.html#http2_clienthttp2session_request_headers_options).
-
-## Abstract
-
-* Fetch-alike
-* Cool-beans 🫐 config options (with defaults)
-* Automatic HTTP/2 support (ALPN negotiation)
-* Automatic or opt-in body parse (with non-UTF-8 charset decoding)
-* Automatic and simplistic `Cookies` treatment (with built-in jar)
-* Automatic decompression (with opt-in body compression)
-* Built-in streamable `File` & `FormData` interfaces
-* Support redirects & retries with fine-grained tune-ups
-* Support all legit request body types (include blobs & streams)
-* Support both CJS and ESM module systems
-* Fully promise-able and pipe-able
-* Zero dependencies
-
-## Prerequisites
-
-* Node.js `>= 16.x`
-
-## Installation
-
-```bash
-npm install rekwest --save
-```
-
-### Usage
-
-```javascript
-import rekwest, { constants } from 'rekwest';
-
-const {
-  HTTP2_HEADER_AUTHORIZATION,
-  HTTP2_HEADER_CONTENT_ENCODING,
-  HTTP2_METHOD_POST,
-  HTTP_STATUS_OK,
-} = constants;
-
-const url = 'https://somewhe.re/somewhat/endpoint';
-
-const res = await rekwest(url, {
-  body: { celestial: 'payload' },
-  headers: {
-    [HTTP2_HEADER_AUTHORIZATION]: 'Bearer [token]',
-    [HTTP2_HEADER_CONTENT_ENCODING]: 'br',  // enables: body compression
-    /** [HTTP2_HEADER_CONTENT_TYPE]
-     * is undue for
-     * Array/Blob/File/FormData/Object/URLSearchParams body types
-     * and will be set automatically, with an option to override it here
-     */
-  },
-  method: HTTP2_METHOD_POST,
-});
-
-console.assert(res.statusCode === HTTP_STATUS_OK);
-console.info(res.headers);
-console.log(res.body);
-```
-
----
-
-```javascript
-import rekwest, {
-  constants,
-  Blob,
-  File,
-  FormData,
-} from 'rekwest';
-import { Readable } from 'stream';
-
-const {
-  HTTP2_HEADER_AUTHORIZATION,
-  HTTP2_HEADER_CONTENT_ENCODING,
-  HTTP2_METHOD_POST,
-  HTTP_STATUS_OK,
-} = constants;
-
-const blob = new Blob(['bits']);
-const file = new File(['bits'], 'file.dab');
-const readable = Readable.from('bits');
-
-const fd = new FormData({
-  aux: Date.now(),  // either [[key, value]], or kv sequenceable
-});
-
-fd.append('celestial', 'payload');
-fd.append('blob', blob, 'blob.dab');
-fd.append('file', file);
-fd.append('readable', readable, 'readable.dab');
-
-const url = 'https://somewhe.re/somewhat/endpoint';
-
-const res = await rekwest(url, {
-  body: fd,
-  headers: {
-    [HTTP2_HEADER_AUTHORIZATION]: 'Bearer [token]',
-    [HTTP2_HEADER_CONTENT_ENCODING]: 'br',  // enables: body compression
-  },
-  method: HTTP2_METHOD_POST,
-});
-
-console.assert(res.statusCode === HTTP_STATUS_OK);
-console.info(res.headers);
-console.log(res.body);
-```
-
-### API
-
-#### `rekwest(url[, options])`
-
-* `url` **{string | URL}** The URL to send the request to
-* `options` **{Object}**
-  Extends [https.RequestOptions](https://nodejs.org/api/https.html#https_https_request_url_options_callback)
-  along with
-  extra [http2.ClientSessionOptions](https://nodejs.org/api/http2.html#http2_http2_connect_authority_options_listener)
-  & [http2.ClientSessionRequestOptions](https://nodejs.org/api/http2.html#http2_clienthttp2session_request_headers_options)
-  and [tls.ConnectionOptions](https://nodejs.org/api/tls.html#tls_tls_connect_options_callback)
-  for HTTP/2 attunes
-  * `body` **{string | Array | ArrayBuffer | ArrayBufferView | AsyncIterator | Blob | Buffer | DataView | File |
-    FormData | Iterator | Object | Readable | SharedArrayBuffer | URLSearchParams}** The body to send with the request
-  * `cookies` **{boolean | Array<[k, v]> | Cookies | Object | URLSearchParams}** `Default: true` The cookies to add to
-    the request
-  * `digest` **{boolean}** `Default: true` Controls whether to read the response stream or simply add a mixin
-  * `follow` **{number}** `Default: 20` The number of redirects to follow
-  * `h2` **{boolean}** `Default: false` Forces the use of HTTP/2 protocol
-  * `headers` **{Object}** The headers to add to the request
-  * `maxRetryAfter` **{number}** The upper limit of `retry-after` header. If unset, it will use `timeout` value
-  * `parse` **{boolean}** `Default: true` Controls whether to parse response body or simply return a buffer
-  * `redirect` **{error | follow | manual}** `Default: follow` Controls the redirect flows
-  * `retry` **{Object}** Represents the retry options
-    * `attempts` **{number}** `Default: 0` The number of retry attempts
-    * `backoffStrategy` **{string}** `Default: interval * Math.log(Math.random() * (Math.E * Math.E - Math.E) + Math.E)`
-      The backoff strategy algorithm that increases logarithmically. To fixate set value to `interval * 1`
-    * `interval` **{number}** `Default: 1e3` The initial retry interval
-    * `retryAfter` **{boolean}** `Default: true` Controls `retry-after` header receptiveness
-    * `statusCodes` **{number[]}** `Default: [429, 503]` The list of status codes to retry on
-  * `thenable` **{boolean}** `Default: false` Controls the promise resolutions
-  * `timeout` **{number}** `Default: 3e5` The number of milliseconds a request can take before termination
-* **Returns:** Promise that resolves to
-  extended [http.IncomingMessage](https://nodejs.org/api/http.html#http_class_http_incomingmessage)
-  or [http2.ClientHttp2Stream](https://nodejs.org/api/http2.html#http2_class_clienthttp2stream) which is respectively
-  readable and duplex streams
-  * if `degist: true` & `parse: true`
-    * `body` **{string | Array | Buffer | Object}** The body based on its content type
-  * if `degist: false`
-    * `arrayBuffer` **{AsyncFunction}** Reads the response and returns **ArrayBuffer**
-    * `blob` **{AsyncFunction}** Reads the response and returns **Blob**
-    * `body` **{AsyncFunction}** Reads the response and returns **Buffer** if `parse: false`
-    * `json` **{AsyncFunction}** Reads the response and returns **Object**
-    * `text` **{AsyncFunction}** Reads the response and returns **String**
-  * `bodyUsed` **{boolean}** Indicates whether the response were read or not
-  * `cookies` **{undefined | Cookies}** The cookies sent and received with the response
-  * `headers` **{Object}** The headers received with the response
-  * `httpVersion` **{string}** Indicates protocol version negotiated with the server
-  * `ok` **{boolean}** Indicates if the response was successful (statusCode: **200-299**)
-  * `redirected` **{boolean}** Indicates if the response is the result of a redirect
-  * `statusCode` **{number}** Indicates the status code of the response
-  * `trailers` **{undefined | Object}** The trailer headers received with the response
-
----
-
-#### `rekwest.defaults`
-
-The object to fulfill with default [options](#rekwesturl-options)
-
----
-
-#### `rekwest.stream(url[, options])`
-
-The method with limited functionality to use with streams and/or pipes
-
-* No automata
-* No redirects
-* Pass `h2: true` in options to use HTTP/2 protocol
-  * Or use `ackn({ url: URL })` method in advance to probe the available protocols
-
----
-
-For more details, please check tests (coverage: **>97%**) in the repository
+The robust request library that humanity deserves 🌐
+---
+This package provides highly likely functional and **easy-to-use** abstraction atop of
+native [http(s).request](https://nodejs.org/api/https.html#https_https_request_url_options_callback)
+and [http2.request](https://nodejs.org/api/http2.html#http2_clienthttp2session_request_headers_options).
+
+## Abstract
+
+* Fetch-alike
+* Cool-beans 🫐 config options (with defaults)
+* Automatic HTTP/2 support (ALPN negotiation)
+* Automatic or opt-in body parse (with non-UTF-8 charset decoding)
+* Automatic and simplistic `Cookies` treatment (with built-in jar)
+* Automatic decompression (with opt-in body compression)
+* Built-in streamable `File` & `FormData` interfaces
+* Support redirects & retries with fine-grained tune-ups
+* Support all legit request body types (include blobs & streams)
+* Support both CJS and ESM module systems
+* Fully promise-able and pipe-able
+* Zero dependencies
+
+## Prerequisites
+
+* Node.js `>= 16.x`
+
+## Installation
+
+```bash
+npm install rekwest --save
+```
+
+### Usage
+
+```javascript
+import rekwest, { constants } from 'rekwest';
+
+const {
+  HTTP2_HEADER_AUTHORIZATION,
+  HTTP2_HEADER_CONTENT_ENCODING,
+  HTTP2_METHOD_POST,
+  HTTP_STATUS_OK,
+} = constants;
+
+const url = 'https://somewhe.re/somewhat/endpoint';
+
+const res = await rekwest(url, {
+  body: { celestial: 'payload' },
+  headers: {
+    [HTTP2_HEADER_AUTHORIZATION]: 'Bearer [token]',
+    [HTTP2_HEADER_CONTENT_ENCODING]: 'br',  // enables: body compression
+    /** [HTTP2_HEADER_CONTENT_TYPE]
+     * is undue for
+     * Array/Blob/File/FormData/Object/URLSearchParams body types
+     * and will be set automatically, with an option to override it here
+     */
+  },
+  method: HTTP2_METHOD_POST,
+});
+
+console.assert(res.statusCode === HTTP_STATUS_OK);
+console.info(res.headers);
+console.log(res.body);
+```
+
+---
+
+```javascript
+import rekwest, {
+  constants,
+  Blob,
+  File,
+  FormData,
+} from 'rekwest';
+import { Readable } from 'node:stream';
+
+const {
+  HTTP2_HEADER_AUTHORIZATION,
+  HTTP2_HEADER_CONTENT_ENCODING,
+  HTTP2_METHOD_POST,
+  HTTP_STATUS_OK,
+} = constants;
+
+const blob = new Blob(['bits']);
+const file = new File(['bits'], 'file.dab');
+const readable = Readable.from('bits');
+
+const fd = new FormData({
+  aux: Date.now(),  // either [[key, value]], or kv sequenceable
+});
+
+fd.append('celestial', 'payload');
+fd.append('blob', blob, 'blob.dab');
+fd.append('file', file);
+fd.append('readable', readable, 'readable.dab');
+
+const url = 'https://somewhe.re/somewhat/endpoint';
+
+const res = await rekwest(url, {
+  body: fd,
+  headers: {
+    [HTTP2_HEADER_AUTHORIZATION]: 'Bearer [token]',
+    [HTTP2_HEADER_CONTENT_ENCODING]: 'br',  // enables: body compression
+  },
+  method: HTTP2_METHOD_POST,
+});
+
+console.assert(res.statusCode === HTTP_STATUS_OK);
+console.info(res.headers);
+console.log(res.body);
+```
+
+### API
+
+#### `rekwest(url[, options])`
+
+* `url` **{string | URL}** The URL to send the request to
+* `options` **{Object}**
+  Extends [https.RequestOptions](https://nodejs.org/api/https.html#https_https_request_url_options_callback)
+  along with
+  extra [http2.ClientSessionOptions](https://nodejs.org/api/http2.html#http2_http2_connect_authority_options_listener)
+  & [http2.ClientSessionRequestOptions](https://nodejs.org/api/http2.html#http2_clienthttp2session_request_headers_options)
+  and [tls.ConnectionOptions](https://nodejs.org/api/tls.html#tls_tls_connect_options_callback)
+  for HTTP/2 attunes
+  * `body` **{string | Array | ArrayBuffer | ArrayBufferView | AsyncIterator | Blob | Buffer | DataView | File |
+    FormData | Iterator | Object | Readable | SharedArrayBuffer | URLSearchParams}** The body to send with the request
+  * `cookies` **{boolean | Array<[k, v]> | Cookies | Object | URLSearchParams}** `Default: true` The cookies to add to
+    the request
+  * `digest` **{boolean}** `Default: true` Controls whether to read the response stream or simply add a mixin
+  * `follow` **{number}** `Default: 20` The number of redirects to follow
+  * `h2` **{boolean}** `Default: false` Forces the use of HTTP/2 protocol
+  * `headers` **{Object}** The headers to add to the request
+  * `maxRetryAfter` **{number}** The upper limit of `retry-after` header. If unset, it will use `timeout` value
+  * `parse` **{boolean}** `Default: true` Controls whether to parse response body or simply return a buffer
+  * `redirect` **{error | follow | manual}** `Default: follow` Controls the redirect flows
+  * `retry` **{Object}** Represents the retry options
+    * `attempts` **{number}** `Default: 0` The number of retry attempts
+    * `backoffStrategy` **{string}** `Default: interval * Math.log(Math.random() * (Math.E * Math.E - Math.E) + Math.E)`
+      The backoff strategy algorithm that increases logarithmically. To fixate set value to `interval * 1`
+    * `interval` **{number}** `Default: 1e3` The initial retry interval
+    * `retryAfter` **{boolean}** `Default: true` Controls `retry-after` header receptiveness
+    * `statusCodes` **{number[]}** `Default: [429, 503]` The list of status codes to retry on
+  * `thenable` **{boolean}** `Default: false` Controls the promise resolutions
+  * `timeout` **{number}** `Default: 3e5` The number of milliseconds a request can take before termination
+  * `trimTrailingSlashes` **{boolean}** `Default: false` Controls whether to trim trailing slashes in the URL before
+    proceed with the request
+* **Returns:** Promise that resolves to
+  extended [http.IncomingMessage](https://nodejs.org/api/http.html#http_class_http_incomingmessage)
+  or [http2.ClientHttp2Stream](https://nodejs.org/api/http2.html#http2_class_clienthttp2stream) which is respectively
+  readable and duplex streams
+  * if `degist: true` & `parse: true`
+    * `body` **{string | Array | Buffer | Object}** The body based on its content type
+  * if `degist: false`
+    * `arrayBuffer` **{AsyncFunction}** Reads the response and returns **ArrayBuffer**
+    * `blob` **{AsyncFunction}** Reads the response and returns **Blob**
+    * `body` **{AsyncFunction}** Reads the response and returns **Buffer** if `parse: false`
+    * `json` **{AsyncFunction}** Reads the response and returns **Object**
+    * `text` **{AsyncFunction}** Reads the response and returns **String**
+  * `bodyUsed` **{boolean}** Indicates whether the response were read or not
+  * `cookies` **{undefined | Cookies}** The cookies sent and received with the response
+  * `headers` **{Object}** The headers received with the response
+  * `httpVersion` **{string}** Indicates protocol version negotiated with the server
+  * `ok` **{boolean}** Indicates if the response was successful (statusCode: **200-299**)
+  * `redirected` **{boolean}** Indicates if the response is the result of a redirect
+  * `statusCode` **{number}** Indicates the status code of the response
+  * `trailers` **{undefined | Object}** The trailer headers received with the response
+
+---
+
+#### `rekwest.defaults`
+
+The object to fulfill with default [options](#rekwesturl-options)
+
+---
+
+#### `rekwest.stream(url[, options])`
+
+The method with limited functionality to use with streams and/or pipes
+
+* No automata
+* No redirects
+* Pass `h2: true` in options to use HTTP/2 protocol
+  * Or use `ackn({ url: URL })` method in advance to probe the available protocols
+
+---
+
+For more details, please check tests (coverage: **>97%**) in the repository

package/dist/ackn.js

@@ -3,13 +3,13 @@
 exports.__esModule = true;
 exports.ackn = void 0;
 
-var _tls = require("tls");
+var _nodeTls = require("node:tls");
 
 const ackn = options => new Promise((resolve, reject) => {
   const {
     url
   } = options;
-  const socket = (0, _tls.connect)({ ...options,
+  const socket = (0, _nodeTls.connect)({ ...options,
     ALPNProtocols: ['h2', 'http/1.1'],
     host: url.hostname,
     port: parseInt(url.port) || 443,

package/dist/cookies.js

@@ -3,6 +3,8 @@
 exports.__esModule = true;
 exports.Cookies = void 0;
 
+var _utils = require("./utils.js");
+
 class Cookies extends URLSearchParams {
   static jar = new Map();
 
@@ -19,6 +21,7 @@ class Cookies extends URLSearchParams {
   }
 
   toString() {
+    (0, _utils.collate)(this, Cookies);
     return super.toString().split('&').join('; ').trim();
   }
 

package/dist/file.js

@@ -3,13 +3,13 @@
 exports.__esModule = true;
 exports.File = void 0;
 
-var _buffer = require("buffer");
+var _nodeBuffer = require("node:buffer");
 
-exports.Blob = _buffer.Blob;
+exports.Blob = _nodeBuffer.Blob;
 
-class File extends _buffer.Blob {
+class File extends _nodeBuffer.Blob {
   static alike(instance) {
-    return [_buffer.Blob.name, File.name].includes(instance?.constructor.name);
+    return [_nodeBuffer.Blob.name, File.name].includes(instance?.constructor.name);
   }
 
   #lastModified;

package/dist/formdata.js

@@ -3,29 +3,29 @@
 exports.__esModule = true;
 exports.FormData = void 0;
 
-var _crypto = require("crypto");
+var _nodeCrypto = require("node:crypto");
 
-var _http = _interopRequireDefault(require("http2"));
+var _nodeHttp = _interopRequireDefault(require("node:http2"));
 
-var _util = require("util");
+var _nodeUtil = require("node:util");
 
 var _file = require("./file.js");
 
-var _helpers = require("./helpers.js");
-
 var _mediatypes = require("./mediatypes.js");
 
+var _utils = require("./utils.js");
+
 function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { default: obj }; }
 
 const CRLF = '\r\n';
 const {
   HTTP2_HEADER_CONTENT_DISPOSITION,
   HTTP2_HEADER_CONTENT_TYPE
-} = _http.default.constants;
+} = _nodeHttp.default.constants;
 
 class FormData {
   static actuate(fd) {
-    const boundary = (0, _crypto.randomBytes)(24).toString('hex');
+    const boundary = (0, _nodeCrypto.randomBytes)(24).toString('hex');
     const contentType = `${_mediatypes.MULTIPART_FORM_DATA}; boundary=${boundary}`;
     const prefix = `--${boundary}${CRLF}${HTTP2_HEADER_CONTENT_DISPOSITION}: form-data`;
 
@@ -44,7 +44,7 @@ class FormData {
             yield encoder.encode(`${prefix}; name="${escape(normalize(name))}"${CRLF.repeat(2)}${normalize(value)}${CRLF}`);
           } else {
             yield encoder.encode(`${prefix}; name="${escape(normalize(name))}"${value.name ? `; filename="${escape(value.name)}"` : ''}${CRLF}${HTTP2_HEADER_CONTENT_TYPE}: ${value.type || _mediatypes.APPLICATION_OCTET_STREAM}${CRLF.repeat(2)}`);
-            yield* (0, _helpers.tap)(value);
+            yield* (0, _utils.tap)(value);
             yield encoder.encode(CRLF);
           }
         }
@@ -60,15 +60,15 @@ class FormData {
   }
 
   static #enfoldEntry(name, value, filename) {
-    name = (0, _util.toUSVString)(name);
-    filename &&= (0, _util.toUSVString)(filename);
+    name = (0, _nodeUtil.toUSVString)(name);
+    filename &&= (0, _nodeUtil.toUSVString)(filename);
 
     if (_file.File.alike(value)) {
       value = new _file.File([value], filename, value);
     } else if (this.#ensureInstance(value)) {
       value.name = filename || value.name;
     } else {
-      value = (0, _util.toUSVString)(value);
+      value = (0, _nodeUtil.toUSVString)(value);
     }
 
     return {
@@ -128,17 +128,20 @@ class FormData {
   }
 
   append(...args) {
+    (0, _utils.collate)(this, FormData);
     this.#ensureArgs(args, 2, 'append');
     this.#entries.push(this.constructor.#enfoldEntry(...args));
   }
 
   delete(...args) {
+    (0, _utils.collate)(this, FormData);
     this.#ensureArgs(args, 1, 'delete');
-    const name = (0, _util.toUSVString)(args[0]);
+    const name = (0, _nodeUtil.toUSVString)(args[0]);
     this.#entries = this.#entries.filter(it => it.name !== name);
   }
 
   forEach(...args) {
+    (0, _utils.collate)(this, FormData);
     this.#ensureArgs(args, 1, 'forEach');
     const [callback, thisArg] = args;
 
@@ -148,24 +151,28 @@ class FormData {
   }
 
   get(...args) {
+    (0, _utils.collate)(this, FormData);
     this.#ensureArgs(args, 1, 'get');
-    const name = (0, _util.toUSVString)(args[0]);
+    const name = (0, _nodeUtil.toUSVString)(args[0]);
     return (this.#entries.find(it => it.name === name) ?? {}).value ?? null;
   }
 
   getAll(...args) {
+    (0, _utils.collate)(this, FormData);
     this.#ensureArgs(args, 1, 'getAll');
-    const name = (0, _util.toUSVString)(args[0]);
+    const name = (0, _nodeUtil.toUSVString)(args[0]);
     return this.#entries.filter(it => it.name === name).map(it => it.value);
   }
 
   has(...args) {
+    (0, _utils.collate)(this, FormData);
     this.#ensureArgs(args, 1, 'has');
-    const name = (0, _util.toUSVString)(args[0]);
+    const name = (0, _nodeUtil.toUSVString)(args[0]);
     return !!this.#entries.find(it => it.name === name);
   }
 
   set(...args) {
+    (0, _utils.collate)(this, FormData);
     this.#ensureArgs(args, 2, 'set');
     const entry = this.constructor.#enfoldEntry(...args);
     const idx = this.#entries.findIndex(it => it.name === entry.name);
@@ -178,6 +185,8 @@ class FormData {
   }
 
   *entries() {
+    (0, _utils.collate)(this, FormData);
+
     for (const {
       name,
       value
@@ -187,18 +196,23 @@ class FormData {
   }
 
   *keys() {
+    (0, _utils.collate)(this, FormData);
+
     for (const [name] of this) {
       yield name;
     }
   }
 
   *values() {
+    (0, _utils.collate)(this, FormData);
+
     for (const [, value] of this) {
       yield value;
     }
   }
 
   [Symbol.iterator]() {
+    (0, _utils.collate)(this, FormData);
     return this.entries();
   }