opensoars/ezreq

Simple (next gen JS) HTTP requests

ezreq

Simple (next gen JS) HTTP requests. (API changes might be incoming soon.. working on a 0.1.0 release).

(Dev note: keep it simple, this is EZreq, not EVERYTHINGreq..)

---

Impression

The code below demonstrates ezreq usage. This code can be used for quick reference, even though it only covers the GET method.

import {GET} from 'ezreq';

// Callback style
GET('http://github.com', (err, res) => {
  if (err) return console.log(`Got error, message: ${err.message}`);
  console.log(`Got res, body length: ${res.body.length}`);
});

// Promise style
GET('http://github.com')
  .then((res) => console.log(`Got res, body length: ${res.body.length}`))
  .catch((err) => console.log(`Got error, message: ${err.message}`));

// Promise style using async await
async () => {
  try {
    const res = await GET('http://github.com');
    console.log(`Got res, body length: ${res.body.length}`);
  }
  catch (err) {
    console.log(`Got error, message: ${err.message}`);
  }
}

Install

Run npm install ezreq

Include

When ezreq is required, it returns an object containing all ezreq functionality.

Add the following line for modern JS:

import {GET, PUT, POST, DELETE} from 'ezreq';

// 3 Character lowercase aliases 
import {get, put, pst, dlt} from 'ezreq';

Add the following lines for older JS:

var ezreq = require('ezreq');
var GET = ezreq.GET;
var PUT = ezreq.PUT;
var POST = ezreq.POST;
var DELETE = ezreq.DELETE;

// 3 Character lowercase aliases
var ezreq = require('ezreq');
var get = ezreq.get;
var put = ezreq.put;
var pst = ezreq.pst;
var dlt = ezreq.dlt;

Use

Basic functionality is described below.

GET (get)

Regular callback handling

Arguments: GET(urlString|optionsObject, [callbackFunction])

GET('http://github.com/opensoars', (err, res) => {
  if (err) return console.log(err);
  console.log(`Got body of length: ${res.body.length}`);
});

Promise callback handling

Arguments: GET(urlString|optionsObject)

GET('http://github.com/opensoars')
  .then((res) => console.log(`Got body of length: ${res.body.length}`))
  .catch((e) => console.log(`On error: ${e.message}`));

Async await

Arguments: GET(urlString|optionsObject)

async () => {
  try {
    const res = await GET('http://github.com/opensoars');
    console.log(`Got body of length: ${res.body.length}`);
  }
  catch (e) { console.log(`On error: ${e.message}`); }
};

PUT (put)

Promise callback handling

PUT();

Async await

PUT();

POST (pst)

Promise callback handling

POST();

Async await

POST();

DELETE (dlt)

Regular callback handling

Arguments: DELETE(urlString|optionsObject, [callbackFunction])

DELETE('http://github.com/opensoars', (err, res) => {
  if (err) return console.log(err);
  console.log(`Got body of length: ${res.body.length}`)
});

Promise callback handling

Arguments: DELETE(urlString|optionsObject)

DELETE('http://github.com/opensoars')
  .then((res) => console.log(`Got body of length: ${res.body.length}`))
  .catch((e) => console.log(`On error: ${e.message}`));

Async await

Arguments: DELETE(urlString|optionsObject)

async () => {
  try {
    const res = await DELETE('http://github.com/opensoars');
    console.log(`Got body of length: ${res.body.length}`);
  }
  catch (e) { console.log(`On error: ${e.message}`); }
};

Develop

The following tools can be used whilst developing ezreq.

Development test_local

Run this command: npm run test_local to run all tests on the local machine and to collect code coverage information. The code coverage report can be found at coverage/lcov-report/index.html.

File watcher which runs test_local and coverage info collector

Run npm run test_watch. The test_watch command runs the test_local command everytime a file change is detected. Customize in order to exclude certain paths or file types.

Documentation

Run the following command to generate documentation from the source code: npm run doc. This will place documentation generated by jsdoc at doc/jsdoc/index.html.

Up next (thoughts)

// Exposed functional API which will be used internal

// 0.1.0 API

// Yes, there'll be a more generic request maker, so that "all" methods
// will be able to share the same logic. Which will of course, limit
// customization.

/**
 * Current fs is ok, how is a general request object going to be server?
 * Am I gonna rewrite? Classes/instances?
 * prolly not..
 * Serious drawing and thinking will be required :)
 */

// url method syntax
// GET;http://opensoars.github.io

// ?
import {GET, PUT, POST, DELETE, REQUEST} from 'ezreq';
const {GET, PUT, POST, DELETE, REQUEST} = require('ezreq');

// ?

const options1 = {
  method: 'GET',
  protocol: 'http:',
  hostname: 'localhost',
  port: 80
};

const options2 = {
  method: 'GET',
  protocol: 'http:',
  hostname: 'www.google.nl',
  port: 80
};

const url1 = 'https://github.com/opensoars'

ezreq.go(options1, (err, res) => {});

ezreq.goEach([options2, url1], (err, res) => {

});

ezreq.goEach([options2, url1], (err, res) => {

});

// Multiple request objects and url strings for 1 callback, how about
// with promises? When is a prom gna resolve? 
// Callback will be called for every request, response object can be used
// to determine which response corresponds to which request.
DELETE([
  'http://google.com',
  {
    hostname: 'www.google.com',
    port: 443,
    method: 'DELETE',
    protocol: 'https:'
  },
  'http://youtube.com'
], callback);

Contributing

1. Fork
2. Create your feature branch (git checkout -b my-epic-feature)
3. Commit your changes (git commit -am 'Add epic feature :)')
4. Push to the branch (git push origin my-epic-feature)
5. Create new Pull Request

Copyright

Copyright (c) 2017 Sam @ Opensoars. See LICENSE for details.