@onepunya/xontol

XONTOL Xtensible, Optimized, No-dependencies, Transparent, Organized, Lightweight

Simple and readable HTTP requests. Promises-based operation. Integrated assertion features. Support for request pooling. Zero external dependencies. Installation Install with: npm install xontol.

Example Usage

Fetching the NodeJS homepage:

const xontol = require('@onepunya/xontol');

const { status, headers, body, assert } = await xontol('GET', 'https://nodejs.org/en/');

Shorthands XONTOL provides shorthand methods for all HTTP verbs:

method(String url [, Object headers] [, String body])

Posting form data:

const { post } = require('@onepunya/xontol');

const { status, headers, body, assert } = await post('https://example.com/', 'key=value&key=value');

Including headers:

const { put } = require('@onepunya/xontol');

const { status, headers, body, assert } = await put(
    'https://example.com/',
    { 'Custom-Header': 'example' },
    'key=value&key=value'
);

To disable automatic content and date headers:

const { put } = require('@onepunya/xontol');

const { status, headers, body } = await put(
    'https://example.com/',
    { 'no-auto': true, 'Custom-Header': 'example' },
    'key=value&key=value'
);

Available HTTP methods in XONTOL:

const xontol = require('@onepunya/xontol');

xontol.get;     //=> [function]
xontol.post;    //=> [function]
xontol.patch;   //=> [function]
xontol.del;     //=> [function]
xontol.put;     //=> [function]
xontol.head;    //=> [function]
xontol.options; //=> [function]

Accessing the raw NodeJS res object, with additional status and body keys:

const { get } = require('@onepunya/xontol');
const res = await get('https://nodejs.org/en/');

Assertions Testing response content:

const { assert } = await get('https://example.com');

// Asserting response body content
assert.body.exactly('expectedContent');
assert.body.contains('expectedContentPart');
assert.body.match(/expectedPattern/);

// Chainable assertions
assert.body.type('application/json').length(42);

// JSON body assertions
assert.body.json
    .hasKey('key')
    .match('key', 'value')
    .empty(); // checks for an empty object

// JSON array assertions
assert.body.json.array
    .match(0, 'expectedValue')
    .includes('expectedValue')
    .length(3)
    .empty(); // checks for an empty array

// Status code assertions
assert.status.is(200);
assert.status.not(404);
assert.status.in([200, 201, 202]);
assert.status.notIn([500, 501, 502]);
assert.status.type(2); // checks for 2xx codes
assert.status.notType(5); // checks for not 5xx codes

// Header assertions
assert.headers
    .has('authorization')
    .match('connection', 'keep-alive');

Authentication

Currently supports Basic and MD5 Digest authentication.

Ensure the server responds with 401 and a WWW-Authenticate header for authentication to work.

Send credentials via the headers object:

const { body } = await post('http://example.com', {
    auth: { username: 'user', password: 'pass' }
});

Alternatively, include the credentials in the URL:

const { body } = await post('http://user:[e-mail]');

Pooling Define a request pool with a max size of 10 requests and a 2-second timeout:

const { Pool } = require('@onepunya/xontol');
const myPool = new Pool({ size: 10, timeout: 2000 });

Execute the pool over a set of request bodies:

const bodies = 'abcdefghijklmnopqrstuvwxyz'.split('');
bodies.forEach(body => myPool.post('http://localhost/fail', body));

Wait for all requests to complete:

// Using promises
const responses = await myPool.done();

// Using events
myPool.on('finish', responses => console.log(responses));

Wait for a single request in the pool to complete:

const res = await myPool.post('http://localhost/fail');

Handle each response individually:

myPool.on('response', (req, res) => {
    console.log(res.status);
});

Contributing mubh mr.one and all