npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

reqex

v1.0.3

Published

Promise based http client with built in retry and JSON validator for response.

Downloads

112

Readme

reqex

NPM Build Coverage License Downloads

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 have body field of string type. The json field will have a parsed JSON object value for all responses which have Content-Type: application/json header, and undefined 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"}'
}