📝 Codepen ・
@d3portillo/ira-fetch-wrapper">🔬 Observable ・
📦 Npm

Ira Fetch: Vanilla JS Fetch API wrapper with goodies 🍒

Irajs is a small ~ 3kb function which enhances current Fetch API with more, more goodies. Ira code isn’t chopped, replaced with random chars or similar on .min.js version, it’s just minified.

Ira goodies include debug logs, persistent settings and custom currying to request functions with a set of options. The little wrapper tries to function using current JS Engine features, no babel or typescript used just plain vanilla Javascript.

Npm Install

npm install irajs

Yarn Install

yarn add irajs

CDN Load

<script src="https://d3portillo.github.io/ira/src/index.min.js"></script>

Usage

import ira from "irajs"
// Requires
const ira = require("irajs")
// Start playing around
ira.get("/stuff")

👉 The complete API reference

Some examples

Getting data

ira.get(`https://postman-echo.com/get?foo1=bar1&foo2=bar2`).then(({ data }) => {
  console.log(data.json, data.text, data.blob) // * Automatic response parsing
})

Adding headers

ira.config({
  headers: {
    "Content-type": "application/json",
  },
})

Parsing blob to base64 string

const blob = new Blob(["something"])
ira.blobToBase64(blob).then((base64) => console.log(base64))

Including a base URL

const request = ira.extend({
  baseURL: "https://yourendpoint.com/dev/branch",
})
// Now you can do
request.get("/binary") //https://yourendpoint.com/dev/branch/binary

Extending a fork

A custom settings fork of main Ira function that’s gapped to provided - config

const request = ira.extend({
  headers: {
    "x-api-key": "somsaltedencryptedawesomekey",
  },
  debug: true /* Shows Ira stuff on console */,
  parseBlob: false /* Do not include .blob on data */,
})
// Now you can make requests containing those settings
request
  .get("https://something")
  .then(({ data: { blob } }) => console.info(null == blob))
// The blob response inside data obj is null

This method extends from Ira Object

The Ira Instance

RESPONSE = {
  data: { json: Object, text: String, blob: ?Blob }
  ok: Boolean,
  status: Number,
  statusText: String,
  statusCode: status<Number>,
  error: ?Error
}
ON_REQUEST_PROPS = {
  headers: {},
  body: ?String,
  debug: ?Boolean,
  parseBlob: ?Boolean,
  params: {},
  ...`https://developer.mozilla.org/en-US/docs/Web/API/Request`
}
IRA_SETTINGS = {
  headers: {},
  debug: Boolean,
  parseBlob: Boolean,
  baseURL: ?String,
}
HTTP_METHODS = {
  get: Function,
  put: Function,
  post: Function,
  head: Function,
  delete: Function,
  connect: Function,
  options: Function,
  trace: Function,
}
// Exported object { Main }
ira = {
  ...HTTP_METHODS,
  default(): HTTP_METHODS.get,
  _settings: Object,
  config: Function,
  extend: Function() => ira /* Fork with provided config */,
  blobToBase64: Function
}

Ira will return a void response if an error ocurred and status of 500.

Ira API Reference

Table of contents

• ira()
• ira.get()
• ira.post()
• ira.put()
• ira.delete()
• ira.connect()
• ira.options()
• ira.trace()
• ira.head()
• ira.blobToBase64()
• ira.on()
• ira.extend()
• ira.config()
• ira._config
• { baseURL }
• { params }
• { debug }
• { parseBlob }

HTTP Methods

This interface rules among many props and methods, ON_REQUEST_PROPS: ira#the-ira-instance

# ira([URL, CONFIG]) <>

URL = "" // Your endpoint URL
CONFIG = ON_REQUEST_PROPS

The GET method, ira("/something") is the same as fetch("/something"). The difference is ira.get returns a Promise which resolves to an Object including .json, .text and .blob methods.

ira().then(({data}) => { data.json | data.text | data.blob })

# ira.get([URL, CONFIG]) <>

URL = "" // That stuff URL
CONFIG = ON_REQUEST_PROPS

Same as ira() method.

# ira.post([URL, CONFIG]) <>

URL = "" // An endpoint
CONFIG = ON_REQUEST_PROPS

The POST method, ira.post("/something") is the same as fetch("/something", { method: "POST" }).

You can include a body doing:

ira.post("/something", {
  body: "some-body",
})

# ira.put([URL, CONFIG]) <>

URL = "" // https://something
CONFIG = ON_REQUEST_PROPS

The HTTP PUT method, ira.put("/api") is the same as fetch("/api", { method: "PUT" }).

You can include a body doing:

ira.put("/something", {
  body: "some-body",
})

You also can show some debug messages on console by adding debug: true.

ira.put("/something", {
  body: "some-body",
  debug: true,
})
// This will log on request start messages and
// When promise is resolved with your data

# ira.delete([URL, CONFIG]) <>

URL = "" // Place an URL here
CONFIG = ON_REQUEST_PROPS

That DELETE Http Method, ira.delete("/api") is the same as fetch("/api", { method: "DELETE" }).

# ira.connect([URL, CONFIG]) <>

URL = "" // The place you want data from
CONFIG = ON_REQUEST_PROPS

Doin a CONNECT method ira.connect("/api") is same as fetch("/api", { method: "CONNECT" }).

You can include this config on your request:

{
  headers: {}, // Your request headers
  body: ?String, // Your request body
  debug: ?Boolean, // if true shows some stuff on console
  parseBlob: ?Boolean, // if false .blob event wont execute
  params: {} // Your URL params ?reqid=3&something=data
}

# ira.options([URL, CONFIG]) <>

URL = "" // That URL you want data from
CONFIG = ON_REQUEST_PROPS

When doing the OPTIONS Http method ira.options("/api") results to be same as doing fetch("/api", { method: "OPTIONS" }).

# ira.trace([URL, CONFIG]) <>

URL = "" // Production or dev endpoint
CONFIG = ON_REQUEST_PROPS

TRACE method, ira.trace("/api") is the same as fetch("/api", { method: "TRACE" }).

# ira.head([URL, CONFIG]) <>

URL = "" // Some resource URL
CONFIG = ON_REQUEST_PROPS

The HEAD method, ira.head("/api") is the same as fetch("/api", { method: "HEAD" }).

Yes, more cool methods

# ira.blobToBase64([Blob]) <>

Blob = new Blob() // A JS Binary long object

You can parse any Blob into a base64 string by doing ira.blobToBase64. This returns a Promise which resolves into a String. This method will always resolve if there’s an error check out you console. If Promise fails will resolve to ""

# ira.on([Event]) <>

Event = "request" | "response"

You can add a custom listener when ira or it’s forks perform a request or when a response is succeded. You can set this triggers like this ira.on("response", callback).

Example:

ira.on("request", (request) => {
  const { url, statusCode, method, headers, config } = request
  if (statusCode == 200) {
    console.log("This will always succeed")
    /*
     This callback is made as soon as request is made
     so statusCode is 200, you can log config, check path and include some magic
    */
  }
})
ira.on("response", (response) => {
  const { url, statusCode, method, headers, config } = request
  // Lets say you want to kick user when it's forbidden
  if (statusCode == 403) killSession()
})

# ira.extend([CONFIG]) <>

CONFIG = {
  headers: {},
  debug: Boolean,
  parseBlob: Boolean,
  baseURL: ?String,
} // @see https://github.com/D3Portillo/ira#the-ira-instance

This method returns a new Ira instance, you can replace default Settings with your custom ones. This can be helpfull if making request to API’s where headers are somewhat “persistent”, for example x-api-key’s or that.

Example:

const request = ira.extend({
  headers: {
    "x-api-key": "somethingawesome",
    "Content-type": "application/json",
  },
})
// Then you can avoid rewriting those headers again
request.get("/endpoint", {
  body: {
    user: "D3Portillo",
    base: "Somebass",
  },
})
// This will include those headers added on .extend call

# ira.config([CONFIG]) <>

CONFIG = {
  headers: {},
  debug: Boolean,
  parseBlob: Boolean,
  baseURL: ?String,
} // @see https://github.com/D3Portillo/ira#the-ira-instance

This method is used to replace current ira or fork settings. This replaces .extend method stuff with those new ones you provide.

const req = ira.extend({
  baseURL: "https://google.com",
})
// Now, let's pretend you want to change that baseURL
req.settings({
  baseURL: "https://duckduckgo.com",
})
// This will replace request's baseURL google.com with duckduck.go

Acces current config

# ira._config\ <>

CONFIG = {
  headers: {},
  debug: Boolean,
  parseBlob: Boolean,
  baseURL: ?String,
} // @see https://github.com/D3Portillo/ira#the-ira-instance

If you want to check current ira config do ira._config. This is supposed to be changed with ira.config(), still you can set ira.\_config.headers = {}

Config[._config] props

# ira._config.baseURL\ <>

You can add a baseURL to make your requests.

ira.settings({
  baseURL: "https://localhost:5000",
})
ira.get("/anurl", {
  params: {
    somelikeparam: "somevalue",
  },
}) // Fetches https://localhost:5000/anurl

# ira._config.params\