Oxhr v1.2.1

An object-oriented and asynchronous XHR (XMLHttpRequest) wrapper.

Modern programmers use fetch, others prefer Oxhr 🐮

Why Oxhr?

• Written in TypeScript
• Promise-based (asynchronous)
• Modular (JavaScript modules)
• Tiny (under 5kb minified)
• No dependencies
• Robust and simple, useful for most tasks
• An alternative to XMLHttpRequest and fetch
• An alternative to feature-rich and complex libraries like axios

A small demo is included, see index.html. If you prefer a plain .js file instead of a modular system you can use a bundler to combine all modules into one file; for such a task I recommend Deno which has a bundle feature.

---

API

Import modules and create a new instance in TypeScript

import { Oxhr } from "./oxhr.js";
import type { IOxhrParams, IRequestHeader } from "./oxhr-types.js";

async function fetchDataExample()
{
  let response: any;
  const options: IOxhrParams = {
    url: "https://...",
    onLoadEnd: () => { alert("Finished!") }
  };

  // The shortest possible call if you don't care about the return type.
  const myConnection = new Oxhr(options);

  // Send request to the server and output response data to console.
  response = await myConnection.send();
  console.log(response);
}

The parameters interface

interface IOxhrParams
{
  url: string;
  method?: "GET" | "POST" | "HEAD" | "PUT" | "DELETE" | "CONNECT" | "OPTIONS" | "TRACE" | "PATCH";
  responseType?: XMLHttpRequestResponseType;
  data?: XMLHttpRequestBodyInit | Document | null;
  requestHeaders?: IRequestHeader[];
  timeoutMs?: number;
  consoleMessage?: string;
  debug?: boolean;
  onLoadEnd?: () => void;
  onProgress?: (percent: number, bytes: number) => void;
  onTimeout?: () => void;
  onAbort?: () => void;
}

Parameters

Parameter	Description	Required	Default	Accepted types
url	URL for http request	x		string
method	HTTP request method	-	"GET"	string ("GET" | "POST" | etc...))
responseType	One of response types	-	""	"", "arraybuffer", "blob", "document", "json", "text"
data	Data to send	-	null	Blob, BufferSource, FormData, URLSearchParams, ReadableStream, string, Document, null
requestHeaders	Array of IRequestHeader	-		IRequestHeader[]
timeoutMs	Timeout in milliseconds. If the request takes longer, it will be terminated.	-	0	number
consoleMessage	Description for console output after loading is done.	-		string
debug	Additional console output	-	false	boolean

Callbacks

Name	Description	Parameters
onLoadEnd	Called after success, timeout, abort or error	--
onProgress	Ongoing loading progress in percent and bytes	(percent: number, bytes: number)
onTimeout	Timeout callback (see timeoutMs parameter)	--
onAbort	When an open connection gets aborted	--

Please note that progress in % must not always work because it depends on server settings (not all connections give you the total data/file size in advance).

Methods

Name	Description	Parameters
send	Sends the request to the server	data?
abort	Aborts an open connection	--

Properties (read-only)

Name	Description
instanceId	A unique ID of the Oxhr instance (UUID).
readyState	The XHR readyState code.
status	The XHR status code.
success	Returns true if transfer was successful (readyState is DONE and status is OK).
isProcessed	Returns true if a request is already being processed.

FAQs

How can I stop a running connection?

• Very easily, you don't need the AbortController() object which is needed for the Fetch API. In Oxhr you simply call the abort method. See the included demo.

Can I open multiple connections at once?

• Yes and no. It's not possible using one instance of Oxhr, but you can create multiple (independent) instances (each instance will have its own unique UUID). Since Oxhr works with EcmaScript's Promise object you can also make use of Promise.all(), Promise.any() etc. Additionally, you can start multiple "await ... send()" requests using one class instance, they will be handled one after another.

Changelog

v1.2.1

• Fixed a too strict connection handling, now the same Oxhr instance can safely be re-used for further requests.

v1.2.0

• Many code improvements, now the library is more robust and handles all kind of wrong usage in a nice way
• Added 4 new getters: instanceId, status, success, isProcessed
• Major code refactoring
• Previous version didn't compile in TypeScript 4.5.4 because of an error, this update fixes it
• Several small bugfixes, one big bugfix for custom onLoadEnd method which didn't get triggered in TypeScript 4.5.4
• Added new "debug" parameter for more verbose console log
• Demo in index.html changed significantly

---

License:

This project is released as permissive free software under the Apache License, Version 2.0 (http://www.apache.org/licenses/LICENSE-2.0)