diff --git a/.nvmrc b/.nvmrc new file mode 100644 index 0000000..25bf17f --- /dev/null +++ b/.nvmrc @@ -0,0 +1 @@ +18 \ No newline at end of file diff --git a/README.md b/README.md index 3f662e2..8d65818 100644 --- a/README.md +++ b/README.md @@ -64,7 +64,7 @@ console.log(res.random); // number ``` ## Opting Out -If you don't want to type your plugin, simply use `any` as the type. This is not recomemnded though as it means all plugins later in the chain will loose the types too, because they have no idea what changes were made. +If you don't want to type your plugin, simply use `any` as the type. This is not recommended though as it means all plugins later in the chain will lose the types too, because they have no idea what changes were made. ```ts const myPlugin: Plugin = (context, next) => {}; diff --git a/docs.md b/docs.md index a2b5794..da8d1eb 100644 --- a/docs.md +++ b/docs.md @@ -1,4 +1,4 @@ -# HttpTranport +# HttpTransport > A flexible, modular REST client built for ease-of-use and resilience @@ -32,7 +32,7 @@ PATCH, DELETE, HEAD are also supported. #### Query strings -Make a HTTP GET request specifiying query strings using `.query` +Make a HTTP GET request specifying query strings using `.query` Single query string ```js @@ -62,7 +62,7 @@ Multiple query strings: #### Headers -Make a HTTP GET request specifiying request headers using `.headers` +Make a HTTP GET request specifying request headers using `.headers` Add a single header: ```js @@ -108,7 +108,7 @@ Convert `Internal Server` responses (500) to errors: ``` `toError` is **only** required if the underlying client does not support HTTP error conversion. -The default transport is `request`, which does **not** convert errors. +The default transport is `node-fetch`, which does **not** convert errors. #### Retries @@ -176,7 +176,7 @@ Middleware are functions that can be executed with before and after a request. M * Terminate a request early e.g for caching purposes * Modify the response object e.g format the response body -Middlware can be executed **per request** using the `.use` method: +Middleware can be executed **per request** using the `.use` method: ```js const exampleMiddleware = require('exampleMiddleware'); @@ -193,7 +193,7 @@ Middlware can be executed **per request** using the `.use` method: } ``` -Middlware can also be executed **for every request** using the `.use` of the client builder. The client builder is created using the `createBuilder` method: +Middleware can also be executed **for every request** using the `.use` of the client builder. The client builder is created using the `createBuilder` method: ```js const exampleMiddleware = require('exampleMiddleware'); @@ -214,7 +214,7 @@ Middlware can also be executed **for every request** using the `.use` of the cli For writing middleware, see the [offical guide](https://github.com/koajs/koa/blob/master/docs/guide.md) -#### Offical HttpTransport middleware +#### Official HttpTransport middleware See [Caching](https://github.com/bbc/http-transport-cache) See [Collapsing](https://github.com/bbc/http-transport-request-collapse) @@ -227,37 +227,30 @@ See [Ratelimiting](https://github.com/bbc/http-transport-rate-limiter) See [xray](https://github.com/bbc/http-transport-xray) -#### Using alternative HTTP clients via transport decorators +#### Callback support +HttpTransport does not support callbacks. However, to integrate with legacy code, use the [callback adapter](https://github.com/bbc/http-transport-callbacks) -Make a HTTP GET request and supply an alternative HTTP transport via `.createClient` +#### Setting default behaviour of underlying http transport -```js -const url = 'http://example.com/'; -const HttpTransport = require('@bbc/http-transport'); -const OtherTransport = require('some-other-transport'); - -const res = await HttpTransport.createClient(OtherTransport) - .get(url) - .asResponse(); - - if (res.statusCode === 200) { - console.log(res.body); - } -``` - -Make a HTTP GET request by configuring an alternative request instance and supplying it in RequestTransport transport via `.createClient` +Make a HTTP GET request by passing default configuration to RequestTransport, and supplying the configured RequestTransport to `.createClient` ```js const url = 'http://example.com/'; const HttpTransport = require('@bbc/http-transport'); -const request = require('request'); -const requestDefaults = { - headers: { - special: 'special value' +const defaultConfig = { + agentOpts: { // Here you can pass in any options for the https agent https://nodejs.org/api/https.html#class-httpsagent + keepAlive: true, + maxSockets: 1000 + }, + defaults: { + json: true, // parses the response body as json + timeout: 2000 // sets timeout for each request + compress: true // support gzip/deflate content encoding. false to disable } }; -const requestTransport = new HttpTransport.RequestTransport(request.defaults(requestDefaults)); + +const requestTransport = new HttpTransport.RequestTransport(defaultConfig); const res = await HttpTransport.createClient(requestTransport); .get(url) @@ -266,7 +259,4 @@ const res = await HttpTransport.createClient(requestTransport); if (res.statusCode === 200) { console.log(res.body); } -``` - -#### Callback support -HttpTransport does not support callbacks. However, to integrate with legacy code, use the [callback adapter](https://github.com/bbc/http-transport-callbacks) +``` \ No newline at end of file diff --git a/docs/HttpTransportBuilder.html b/docs/HttpTransportBuilder.html index 494ec72..bedbe3e 100644 --- a/docs/HttpTransportBuilder.html +++ b/docs/HttpTransportBuilder.html @@ -23,7 +23,7 @@
@@ -66,7 +66,7 @@

n
Source:
@@ -205,7 +205,7 @@

Methods

-

asCallback()

+

createClient()

@@ -217,106 +217,7 @@

asCallback<
Source:
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-

Callbackify the client

-
- - - - - - - - - -

Example
- - 
const client = httpTransport.asCallback().createClient();
- - - - - - - - - - - - - - - - -
Returns:
- - -
-

a HttpTransport instance supporting callbacks

-
- - - - - - - - - - - -

createClient(fn)

- - - - - - -
- - -
Source:
-
@@ -374,55 +275,6 @@
Example
-
Parameters:
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDescription
fn - - -function - - - -

a global plugin

- - @@ -464,7 +316,7 @@

retriesSource:
@@ -615,7 +467,7 @@

retryDelay<
Source:
@@ -766,7 +618,7 @@

useSource:
@@ -918,7 +770,7 @@

userAgentSource:
@@ -1020,7 +872,7 @@
Parameters:
-

user agant

+

user agent

@@ -1070,7 +922,7 @@
Returns:

- Documentation generated by JSDoc 3.5.5 on Thu Feb 07 2019 15:28:34 GMT+0000 (Greenwich Mean Time) using the docdash theme. + Documentation generated by JSDoc 3.6.11 on Fri Sep 22 2023 15:20:00 GMT+0100 (British Summer Time) using the docdash theme.
diff --git a/docs/HttpTransportClient.html b/docs/HttpTransportClient.html index 484fe96..f7cb2ea 100644 --- a/docs/HttpTransportClient.html +++ b/docs/HttpTransportClient.html @@ -23,7 +23,7 @@
@@ -70,7 +70,7 @@

ne
Source:
@@ -187,7 +187,7 @@

Parameters:
-

default configutation

+

default configuration

@@ -244,7 +244,7 @@

(async) asBody<
Source:
@@ -324,7 +324,10 @@

Returns:

a Promise. If the Promise fulfils, -the fulfilment value is the response body, as a string by default.

+the fulfilment value is the response body. The body type defaults to string. +If the content-type response header contains 'json' +or the json: true option has been set on transport layer +then the body type will be json.

@@ -349,7 +352,7 @@

(async) asR
Source:
@@ -442,7 +445,7 @@

Returns:
-

delete(url, request)

+

delete(baseUrl)

@@ -454,7 +457,7 @@

deleteSource:
@@ -510,7 +513,7 @@
Example
const httpTransport = require('@bbc/http-transport');
 
 const response = await httpTransport.createClient()
-   .delete(url)
+   .delete(baseUrl)
    .asResponse();
@@ -541,7 +544,7 @@
Parameters:
- url + baseUrl @@ -561,29 +564,6 @@
Parameters:
- - - - request - - - - - -object - - - - - - - - - -

body

- - - @@ -617,7 +597,7 @@
Returns:
-

get(url)

+

get(baseUrl)

@@ -629,7 +609,7 @@

getSource:
@@ -716,7 +696,7 @@
Parameters:
- url + baseUrl @@ -769,7 +749,7 @@
Returns:
- + @@ -781,7 +761,7 @@