@bitfluent/wirejs v1.0.7

Wire.js

A simple, class-based library for managing AJAX requests. Uses the Fetch API and other ES8 features. Currently in VERY early development. I wouldn't recommend using in production at this point; many holes need to be filled and features added.

Why Wire?

Many HTTP request libraries exist, so why Wire? Since Wire is class-based, we can create instances with preferences for each REST API service our application uses. This helps with staying organized and makes future API interactions a breeze.

Even better, since Wire is a js class, you can extend it in nearly unlimited creative ways to better suit your individual use case. For example, if the API service you're consuming requires that you first log in to receive an authentication token, you have the ability to extend Wire to do just that, and apply said token to future HTTP requests. "Smart" HTTP requests are the best requests. :)

Installing & Importing

Browser

In your HTML document, include wire.js in your <script> tag. If using in an existing js file, simply import it:

import Wire from 'wire.js';

Node

Run npm install @bitfluent/wirejs and import to your application. Only supports module types.

import Wire from '@bitfluent/wirejs';

Wire Instances and Configuration

Creating an instance

Create a new instance of Wire for repeated usage in your document/application. Pass the options object as an argument to configure. Leaving an option out will assume the default.

const wireOptions = {};
const api = new Wire(wireOptions);

The Options Object

The options object is passed as an argument into new instances of Wire. Each property is used as follows:

apiRoot: The root URI for requests made with this instance. Default is ''.
headers: An object containing any headers to be sent with this instance. It's recommended that you place any authorization headers here for the instance. Default value is { 'Content-Type': 'application/json' }.
auth: Can be a string or a function that returns a string. Whatever is returned by the function will be placed into the Authorization header for each request made by the Wire instance. Using a function to return a value is handy when the authorization token changes or is updated often, as the function will always return the most recent value before every API call.
includeCredentials: A boolean value that determines if cookies should be sent with cross-origin requests. Default value is false.
returnJSON: A boolean value that determines if JSON.parse should be called upon receiving a response. If invalid JSON is retrieved from the server, text will be returned instead. Default value is false.

Example:

const api = new Wire({
	apiRoot: 'https://localhost:3000/api/v1',
	headers: {
		'Content-Type': 'application/json; charset=UTF-8',
		// Add any additional headers go here.
	},
	auth: () => {
		return `Bearer ${myToken}`;
	},
	includeCredentials: true,
	returnJSON: true,
});

Now that we've declared our new Wire instance as api, we will use that to make any requests going forward.

GET Example:

The get() method accepts two arguments. api.get(path, handleErrors).

async function getUser() {
	let user = await api.get('/users/johndoe/', (err) => {
		console.error(err);
	});

	console.log(user); // Do whatever you want with the server's response.
}

POST Example:

The post() method accepts three arguments. api.post(path, body, handleErrors).

let postData = { firstname: 'John', lastname: 'Doe' };

async function createUser() {
	let submission = await api.post('/user/', postData, (err) => {
		console.error(err);
	});

	console.log(submission); // Do whatever you want with the server's response.
}

PUT Example:

The put() method accepts three arguments. api.put(path, body, handleErrors).

let newData = { firstname: 'Jane', lastname: 'Doe' };

async function updateUser() {
	let submission = await api.put('/user/49875432327/', newData, (err) => {
		console.error(err);
	});

	console.log(submission); // Do whatever you want with the server's response.
}

DELETE Example:

The delete() method accepts two arguments. api.delete(path, handleErrors).

async function removeUser() {
	let submission = await api.delete('/user/49875432327/', (err) => {
		console.error(err);
	});

	console.log(submission); // Do whatever you want with the server's response.
}