/JHRW

A wrapper for so-called "AJAX" Requests

Primary LanguageJavaScriptApache License 2.0Apache-2.0

JHRW - JavaScript HTTP Request Wrapper

A wrapper for so-called "AJAX" Requests

Goals

I've made JHRW to:

  • Advance my JavaScript skills;
  • Improve/Simplify the usage of the XMLHttpRequest object by:
    • Adding default values to what's undefined;
    • Adding additional Error checking and clarification;
    • Adding interesting, simplified, feature, such as timeouts and retries.

Documentation

Object JHRW(String base, String urlPath [, Boolean lazyExecution = false [, Boolean bypassCache = false]]);

Parameters

  • String base - The request's base URL
  • String urlPath - The request's endpoint
  • Boolean lazyExecution(optional) - If the request should be initialized and sent right after instantiation. Default: false
  • Boolean bypassCache(optional) - If the request URL should have a timed parameter added in order to bypass cache. Default: false

Throws

  • A ReferenceError
    • If there's no JHRWHandler function defined.
  • A Error
    • if the base parameter is undefined
    • if the urlPath parameter is undefined
  • A TypeError
    • if the base parameter is not a String
    • if the urlPath parameter is not a String
    • if the lazyExecution parameter is not a Boolean
    • if the bypassCache parameter is not a Boolean

Returns

An Object containing:

Properties

  • Object request - The native XMLHttpRequest Object
  • Object config - The configuration Object
    • String URI - The request's target
    • Boolean asynchronous - If the request should be asynchronous
    • String verb - The HTTP verb
    • Mixed data - Data to be sent along with the request
    • Object requestHeaders - HTTP headers for the request
    • String responseType - Expected MIME type of the response
    • Object handlers - The functions to handle the request
    • Number attempts - # of attempts to retry if the request fails
    • Number attemptInterval - Interval between attempts, in seconds.
    • Number timeout - The timeout, in seconds, for the request - after which it should be retried.
    • Function postTimeout: The function to be executed if the request times out.
    • Number timer - The timer that controls the retry process.
Static Properties
  • Array JHRW.availableHandlers: The types of handlers that can be [re-]defined.
  • String JHRW.handlerList: Convenience property to be shown in error messages.

Methods

configure
void configure(Object configureObject);

Overwrites one or more configuration options (see the config object above)

init
void init();

Initializes the request: Sets the expected response MIME Type; Sets the handlers as listeners; Opens the request; Sets the request's headers.

send
void send();

Sends the request, including data, if available.

end
void end();

Ends the request. Useful if you wish for JHRW to stop retrying on success.

Basic Usage

try {
	var obj = new JHRW('http://localhost', /foo.php', true);
} catch (Error e) {
	// Do something
}

or

try {
	var req = new JHRW('http://localhost', 'foo.php');

	try {
        req.init();
	} catch (ReferenceError e) {
        // Do something
    }

    req.send();
} catch (Error e) {
    // Do something
}

For a more advanced usage example see the testing page.

Credits