Nonviolent Pirate Mobster

    owp.http

    2.0.1 • Public • Published

    OpenWebProject HTTP

    HTTP client for JavaScript

    HTTP is a simple and lightweight wrapper for the browsers native XMLHttpRequest functionality.
    The purpose of this utility is to easiliy enable HTTP request without relying on a large framework. No matter if you have a simple standard JS app, uses jQuery or react framework you can make use of HTTP request in the same way.

    Installation and use

    npm install owp.http --save
    
    import HTTP from "owp.http";

    Static requests

    HTTP.useOptions(options);
    const promise = HTTP.get("http://www.mysite.com/rest/data", options);
    const promise = HTTP.delete("http://www.mysite.com/rest/data", options);
    const promise = HTTP.head("http://www.mysite.com/rest/data", options);
    const promise = HTTP.post("http://www.mysite.com/rest/data", options);
    const promise = HTTP.put("http://www.mysite.com/rest/data", options);
    const promise = HTTP.patch("http://www.mysite.com/rest/data", options);
    const promise = HTTP.jsonp("http://www.mysite.com/rest/data", options);

    Instance requests

    HTTP.useOptions(options);
    const http = new HTTP("http://www.mysite.com/rest", options);
    const promise = http.get("data", options);
    const promise = http.delete("data", options);
    const promise = http.head("data", options);
    const promise = http.post("data", options);
    const promise = http.put("data", options);
    const promise = http.patch("data", options);
    const promise = http.jsonp("data", options);

    Options

    Name Description
    headers Headers
    params Query parameters
    data Data payload
    json JSON data payload
    fullResponse Set to true to get full response
    contentType Media type(MIME) for data payload
    responseType Type for response data
    cache Set to true to cache responses
    stateChangeInterceptor State change interceptor callback
    requestInterceptor Request interceptor callback
    responseInterceptor Response interceptor callback
    download Set to true to download response data
    filename Filename for downloaded file

    Options inheritence

    • Add options to the class with useOptions(options)
      • Inherits NO options
    • Add options to the static request HTTP.get("URL", options)
      • Inherits CLASS options
    • Add options to the instance new HTTP("URL", options)
      • Inherits CLASS options
    • Add options to the instance request http.get("PATH", options)
      • Inherits INSTANCE options

    Path parameters

    const id = "Fo%Bar";
    
    //Static request. All paths string after the first(base) one is uri encoded.
    const promise = HTTP.get("http://www.mysite.com/rest/data", id, "subpath");
    
    //Instance constructor. All paths string after the first(base) one is uri encoded.
    const http = new HTTP("http://www.mysite.com", "rest");
    //Instance request. All path string are uri encoded.
    const promise = http.get("data", id, "subpath");
    //Instance request at base path.
    const promise = http.get();

    Headers and query parameters

    //Headers. Flat object(key/value map)
    const headers = { Origin:  "http://www.mysite.com" };
    
    //Query parameters. Object(key/value map) which supports multiple values per key.
    //?id=123&field=name&field=value
    const params = { id: "123", field: [ "name", "value" ] };
    
    //Can be used for static requests.
    const promise = HTTP.get("http://www.mysite.com/rest/data", { headers: headers, params: params });
    
    //Can be given to the constructor and passed to each request.
    const http = new HTTP("http://www.mysite.com/rest", { headers: headers, params: params });
    
    //Can be defined for single request.
    const promise = http.get("data", { headers: headers, params: params });

    Payload

    Payload parameters are the same for post/put/patch.

    //Data with specified content type.
    const promise = http.post({ data: "myData", contentType: "text/plain" })
    //Data with undefined content type. String/boolean/number defaults to "text/plain".
    const promise = http.post({ data: "myData" })
    //Unspecified objects are converted to urlencoded query string a=1&b=2 with content type: "application/x-www-form-urlencoded".
    const promise = http.post({ data: { a: 1, b: 2 } })
    //Json object. Object is stringified and content type is "application/json".
    const promise = http.post({ json: { a: 1, b: 2 } })

    Response

    Resolved promise returns payload.

    http.get()
        .then(function(response) {
            //Response from server if promise resolved(request succeeded).
        })
        .catch(function(error) {
            //Full response object if promise rejected(request failed). Se  below for description of full response.
        });

    Full response

    Get a full response in both promise resolve and reject.

    http.get({ fullResponse: true })
        .then(function(response) {
            //Full response returned.
        });
    
    //Full response format.
    {
        ok: true,
        url: "http://www.mysite.com/rest/data?id=123",
        status: 200,
        statusText: "OK",
        text: "{ value: 5 }",
        //Data is the same value that is returned in a simple(non full) response.
        data: { value: 5 },
        //Object with headers
        headers: { }
    }

    Response type

    Specify response type. Can be used to request binary data

    http.get({ responseType: "blob" })
        .then(function(blob) {
            //Blob containing binary data
        });

    Cache

    Enable cache. Matches method+url and caches response.

    http.get({ cache: true })
        .then(function(cachedResponse) {
            //Response is fetched from cache.
        });

    State change interceptor

    Callback to trigger on every state change on the underlying XMLHttp​Request​.
    0 UNSENT - Client has been created. open() not called yet.
    1 OPENED - open() has been called.
    2 HEADERS_RECEIVED - send() has been called, and headers and status are available.
    3 LOADING - Downloading; responseText holds partial data.
    4 DONE - The operation is complete.

    stateChangeInterceptor: function (readyState) {
        switch (readyState) {
            //readyState = [0, 4]
        }
    };

    Request interceptor

    Callback to format/update request. Useful for updating auth credentials.

    requestInterceptor: function(request: object) {
        //Update auth credentials
        request.headers.Authorization = "...";
        //Return updated request
        return request;
        //Or return Promise.
        return Promise.resolve(request);
        //Returning rejected promise rejects the entire http request.
        return Promise.reject("Error");
    }

    Response interceptor

    Callback to format/update response. Useful for logging errors.

    responseInterceptor: function(response: object) {
        //Change response
        if (response.data === null) {
            response.data = "No Data, but ok";
        }
        //Log errors
        if (!response.ok) {
            console.error(response.statusText);
        }
        //Return updated response.
        return response;
        //Or return Promise.
        return Promise.resolve(response);
        //Returning rejected promise rejects the entire http request.
        return Promise.reject("Error");
    }

    Install

    npm i owp.http

    DownloadsWeekly Downloads

    18

    Version

    2.0.1

    License

    MIT

    Unpacked Size

    21.3 kB

    Total Files

    8

    Last publish

    Collaborators

    • andreas_arvidsson