@bimo2/visa v1.0.0-alpha.1

visa

An ultra-light async HTTP library for web apps. Visa uses promises and a simple uniform API to make HTTP requests using the built-in Fetch API on modern browsers or XMLHttpRequest on legacy browsers.

alpha.1 Notes

This alpha release is exported as an ES module and must in imported into projects with ES modules enabled and that use the node specifier resolution to resolve .js files. The following flags should be used in Node.js < 14.0.0:

$ node --experimental-modules --experimental-specifier-resolution=node index

Install + Build

1.0.0 alpha releases are currently only available via npm due to the dependence on ES modules and new ES features.

$ npm install @bimo2/visa

You can then import the visa module:

import visa from '@bimo2/visa';

Docs

Perform a simple get request:

(async () => {
  try {
    const res = await visa.get('https://replay-api.now.sh/api');
    console.log(res);
  }
  catch (e) {
    console.log(e);
  }
})();

Request API

Visa requests support the GET, POST, PUT, PATCH, DELETE, HEAD and OPTIONS HTTP methods. All visa requests return a promise that resolves to a VisaResponse object or rejects with a VisaError object. The request API has the following configuration:

visa.<method>(url[, options]);

<method> is the HTTP method (i.e. post) and url is the request URL. Both these parameters are required. options is an optional object with all or none of the following properties query, body, headers, timeout and credentials.

visa.post('https://replay-api.now.sh/api/201', {
  query: {
    ex: 'travel'
  },
  body: {
    airline: 'WestJet',
    flight: 'WS-647',
    passengers: [
      {
        name: 'Chloe',
        seat: '38H'
      },
      {
        name: 'Alex',
        seat: '38K'
      }
    ]
  },
  headers: {
    'Content-Type': 'application/json'
  },
  timeout: 1500,
  credentials: true
});

query is an object that will be stringified into a querystring. Nested objects in the query will be stringified using JSON.stringify().

body is an object conatining the request body. Bodies will be sent for any request except GET and HEAD. body should be a string and will throw an error otherwise, however, if the the Content-Type header is set to application/json the body will be stringified automatically using JSON.stringify().

headers is an object containing the request headers.

timeout (if specified) should be a number in milliseconds that will force the request to timeout after the specified amount of time.

credentials should be a boolean that determines what value for credentials will be passed to the underlying HTTP function. For the Fetch API, true will use include as the credentials value and false will use omit. The default is same-origin. For XMLHttpRequest, the boolean will be passed to xhr.withCredentials.

VisaResponse

Visa responses (once resolved) will be an object with the following format:

{
  body: {
    booked: true
  },
  headers: {
    'Content-Type': 'application/json',
    'Cache-Control': 's-maxage=0',
    'X-Powered-By': 'replay'
  },
  status: 201
}

body will be parsed with JSON.parse() if the server Content-Type header is application/json.

VisaError

Visa will throw an error if the request has failed or if the response status is an HTTP error (code >= 400). VisaError extends Error and will have a message and name property:

if (e.name === 'VisaError') {
  // this is a VisaError
}

VisaErrors will also have a body, headers and status property like visa responses.

Examples

• Visa - API Testing

License

MIT © Bimal Bhagrath