reqex
v1.0.3
Published
Promise based http client with built in retry and JSON validator for response.
Downloads
69
Maintainers
Readme
reqex
Promise based http client with built in retry and JSON validator for response.
Installation
npm install reqex
Description
reqex - is a simple http(s) client which allows to perform
GET
, POST
, PUT
and DELETE
requests.
Also response will contain parsed json and could return it
with a type if validate
method is used.
Implemented for convenience with types, and ability to chain request
methods. Also supports pipe
method for streaming response to writable/duplex stream.
Usage
Import reqex
to the TS/JS projects:
// ESM or TypeScript projects:
import reqex from 'reqex';
// CommonJS projects:
const { reqex } = require('reqex');
Note
All responses for any
Content-Type
will havebody
field of string type. Thejson
field will have a parsed JSON object value for all responses which haveContent-Type: application/json
header, andundefined
value for all other types.
GET
const response = await reqex.get('http://localhost:3000/user');
console.log(response);
Expected output:
{
status: 200,
ok: true,
contentLength: 23,
headers: {
'x-powered-by': 'Express',
'content-type': 'application/json; charset=utf-8',
'content-length': '23',
etag: 'W/"17-notW5/nnoifrwkOLKeW655Vz8Xg"',
date: 'Fri, 15 Sep 2023 10:38:05 GMT',
connection: 'close'
},
json: { user: { name: 'some user', id: 'some id' } },
body: '{"user":{"name":"some user","id":"some id"}}'
}
POST
const response = await reqex
.post('http://localhost:3000/user')
.body({ name: 'some new user' });
console.log(response);
Expected output:
{
status: 201,
ok: true,
contentLength: 52,
headers: {
'x-powered-by': 'Express',
'content-type': 'application/json; charset=utf-8',
'content-length': '52',
etag: 'W/"34-vZ5QItgbUr7K7/mmx0UbwgRbD+w"',
date: 'Fri, 15 Sep 2023 10:45:34 GMT',
connection: 'close'
},
json: { user: { name: 'some new user', id: 'some new id' } },
body: '{"user":{"name":"some new user","id":"some new id"}}'
}
PUT
const response = await reqex
.put('http://localhost:3000/user')
.body({ name: 'some updated user' });
console.log(response);
Expected output:
{
status: 200,
ok: true,
contentLength: 60,
headers: {
'x-powered-by': 'Express',
'content-type': 'application/json; charset=utf-8',
'content-length': '60',
etag: 'W/"3c-EIJ+q9sLuMYRrdJsituIMyqNoJw"',
date: 'Fri, 15 Sep 2023 10:47:09 GMT',
connection: 'close'
},
json: { user: { name: 'some updated user', id: 'some updated id' } },
body: '{"user":{"name":"some updated user","id":"some updated id"}}'
}
DELETE
const response = await reqex
.delete('http://localhost:3000/user')
.body({ name: 'some user' });
console.log(response);
Expected output:
{
status: 204,
ok: true,
contentLength: 0,
headers: {
'x-powered-by': 'Express',
date: 'Fri, 15 Sep 2023 10:48:00 GMT',
connection: 'close'
},
json: undefined,
body: ''
}
Retry
Note
If
retry
method was called -pipe
method will be disregarded.
Does not mean to be used for 400+ status codes, but for connection errors and etc.
If troubles with API for performing requests to are possible - retry
method can handle such requests and automatically perform new one.
By default retries to do request in 10 seconds. Max interval time can be 60 seconds, and max amount of attempts - 15 times. If bigger value is passed - max value will be set.
Following example will perform up to 3 additional requests, if main request has failed:
const response = await reqex
.get('http://localhost:3000/possible-unavailable')
.retry({ attempts: 3 });
Also, next request time can be specified (example - 25 seconds), and log can be added:
const response = await reqex
.get('http://localhost:3000/possible-unavailable')
.retry({ attempts: 3, interval: 25, logOnRetry: true });
Pipe
Note
If
retry
method was called -pipe
method will be disregarded.
Allows to pipe response to any writable
/duplex
stream. Also returns response as
reqex.get()
request:
const stream = fs.createWriteStream('out.json');
const response = await reqex.get('http://localhost:3000/users').pipe(stream);
VALIDATE RESPONSE DATA
The vator library is used for validation.
.validate()
method is designed to assert data is matches provided schema.
In case of wrong type - error will be thrown.
import { v } from 'reqex'
const { json } = await reqex
.get('http://localhost:3000/user')
.validate({
name: v.string;
id: v.number;
});
const { name, id } = json;
console.log(`The "name" field has type "${typeof name}" and value "${name}"`);
console.log(`The "id" field has type "${typeof id}" and value "${id}"`);
Expected output:
The "name" field has type "string" and value "some user"
The "id" field has type "number" and value "123"
NOT JSON CONTENT-TYPE
const response = await reqex
.get('http://localhost:3000/')
.headers({ 'content-type': 'text/html' });
console.log(response);
Expected output:
{
status: 200,
ok: true,
contentLength: 20,
headers: {
'x-powered-by': 'Express',
'content-type': 'text/html; charset=utf-8',
'content-length': '20',
etag: 'W/"14-XVEfTf8cEMbur8HQBK5MH4vJQ7U"',
date: 'Fri, 15 Sep 2023 10:52:59 GMT',
connection: 'close'
},
json: undefined,
body: '<h1>Hello reqex!</h1>'
}
400+ status code responses
Lets pretend your server responds with json
content-type for 404 Not Found
cases:
const response = await reqex.get('http://localhost:3000/not-found');
console.log(response);
Expected output:
{
status: 404,
ok: false,
contentLength: 23,
headers: {
'x-powered-by': 'Express',
'content-type': 'application/json; charset=utf-8',
'content-length': '23',
etag: 'W/"17-SuRA/yvUWUo8rK6x7dKURLeBo+0"',
date: 'Fri, 15 Sep 2023 11:04:07 GMT',
connection: 'close'
},
json: { message: 'Not Found' },
body: '{"message":"Not Found"}'
}