dame minimalistic HTTP client for the browser and Node.js

• 🚀 Lightweight
• ⚪️ Zero dependencies.
• 😀 Easy to use.
• 🟢 Node (http & https) and 💻 browser (Fetch).
• 👉 Promise API.
• ⌛ Custom timeout.
• 📄 Automatic transforms to JSON data.
• ⏭ Follows redirects.

📃 Changelog

Table of contents

• Table of contents
• Import
• Basic examples
• Response object
• Methods
  • get, delete
  • post, put, patch
• Config
• Configuring base instance
• Creating an instance
  • Examples
  • Editing an instance
• Special statuses
• dame vs. others
• ☝ Return to top

Import

const dame = require("dame");

Basic examples

GET

const {response} = dame.get("https://rickandmortyapi.com/api/location/1");

POST

const {response} = dame.post("https://your.api.com/login", {
	username: "Username",
	password: "****",
});

Response object

{
	isError: false,
	code: 200,
	status: "OK",
	response: {...},
	error: null,
	redirectCount: 3,
}

• isError boolean: True if code is >= 200 and < 300 (this is configurable).
• code number: Status code.
• status string: Status.
• response any: Response of the request.
• error any: If there was any error during the request it will be here.
• redirectCount number: How many redirects have been followed. Not present if there have been no redirects.

The response can be destructured like this:

const {isError, code, status, response} = dame.get("https://rickandmortyapi.com/api/location/1");

Methods

get, delete

const {response} = dame.get(url, config);
const {response} = dame.delete(url, config);

• url string: Full URL or path.
  • If you set a baseUrl, this url will be concatenated to it: baseUrl + url.
  • If url starts with "http://" or "https://" the baseUrl from config will be ignored and url will be treated like a full url.
• config object: See Config.

post, put, patch

const {response} = dame.post(url, body, config);
const {response} = dame.put(url, body, config);
const {response} = dame.patch(url, body, config);

• url string:See get.
• body object: The request body.
• config object: See Config.

Config

• baseUrl string: Base URL that will be concatenated with the url of the requests.
• headers object: Headers that will be attached to the request.
• timeout number: Number of miliseconds that must pass before timeout the request.
• checkIsError function<boolean>: Function that will receive the status code (number) and must return boolean. Default isError = !(code >= 200 && < 300).
• Any option that fits on request or fetch.
• maxRedirects number: Max redirects to follow. Default 20. Use 0 to disable redirects.
• responseType "arraybuffer" | "stream" | "json" | "text": Browser only. Default "json". Type of the data that the server will respond with.

Configuring base instance

Syntax:

dame.<configKey> = <value>;

• configKey: any key from Config.
• value: any value that fits on the config key.

Examples:

dame.baseUrl = "http://localhost:3010";
dame.headers.Authorization = `Bearer abcd.1234`;
dame.timeout = 5000;

Then you'll be able to:

dame.get("/protectedRoute");
// url will be → http://localhost:3010/protectedRoute
// headers will be → {Authorization: "Bearer abcd.1234"}

Creating an instance

const dameInstance = dame.new(config, instanceName?);

• config object: See Config.
• instanceName string: (optional) If filled, this instance will be saved on dame.instances.<instanceName>.

Removing a saved instance:

delete dame.instances.<instanceNameToRemove>

Examples

Set base URL

const yourApi = dame.new({
	"baseUrl": "http://localhost:3000",
});

Set headers

const yourApi = dame.new({
	"headers": {
		Authorization: "Bearer abc.123"
	}
});

Editing an instance

yourApi.headers.Authorization: "Bearer new.token";

Special statuses

Timeout

{
	isError: true,
	code: 0,
	status: 'Timed out',
	response: null
}

No response

{
	isError: true,
	code: -1,
	status: "No response from server",
	response: null
}

Offline

{
	isError: true,
	code: -2,
	status: "No internet connection",
	response: null
}

dame vs. others

Package | Browser + Node | Dependencies | Size :---: | :---: | :---: | :---: dame | ✅ | 0 | phin | ❌ | | node-fetch | ❌ | | axios | ✅ | | got | ❌ | | superagent | ✅ | | request | ❌ | |

☝ Return to top