web-request
    TypeScript icon, indicating that this package has built-in type declarations

    1.0.7 • Public • Published

    web-request

    Simplifies making web requests with TypeScript async/await

    This package makes it easier to perform web requests using TypeScript and async/await. It wraps the popular request package, extending it with an interface that facilitates async/await and strong-typing.

    Examples

    Get web-page content as a string...

    var result = await WebRequest.get('http://www.google.com/');
    console.log(result.content);

    Get JSON data...

    var url = 'http://query.yahooapis.com/v1/public/yql?q=select+*+from+yahoo.finance.quotes+where+symbol+IN+(%22YHOO%22,%22AAPL%22)&format=json&env=http://datatables.org/alltables.env';
    var data = await WebRequest.json<any>(url);
    for (var quote of data.query.results.quote)
        console.log(quote.Symbol, quote.Bid, 'low='+quote.DaysLow, 'high='+quote.DaysHigh, 'vol='+quote.Volume);  

    Get JSON data with a strongly typed result...

    interface QuoteResult {
        query: {
            results: {
                quote: Array<{
                    Symbol: string;
                    Bid: string;
                    DaysHigh: string;
                    DaysLow: string;
                    Volume: string;
                }>
            }
        }
    }    
    var url = 'http://query.yahooapis.com/v1/public/yql?q=select+*+from+yahoo.finance.quotes+where+symbol+IN+(%22YHOO%22,%22AAPL%22)&format=json&env=http://datatables.org/alltables.env';
    var data = await WebRequest.json<QuoteResult>(url);
    for (var quote of data.query.results.quote)
        console.log(quote.Symbol, quote.Bid, 'low='+quote.DaysLow, 'high='+quote.DaysHigh, 'vol='+quote.Volume);  

    Perform a series of REST operations, one-by-one...

    // Transfer all orders from customer #123 to customer #321 and then delete customer #123...
    var orders = await WebRequest.json<Order[]>('http://www.example.com/customers/123/orders');
    // Change status of all orders to backorder...
    for (var order of orders)
        order.status = "backorder";
    await WebRequest.post('http://www.example.com/customers/321/orders', null, orders);
    await WebRequest.delete('http://www.example.com/customers/123');
    // Flag order #98765 as shipped...
    await WebRequest.patch('http://www.example.com/customers/321/orders/98765', null, {status: "shipped"});

    Getting Started

    Make sure you're running Node v4 and TypeScript 1.7 or higher...

    $ node -v
    v4.2.6
    $ npm install -g typescript tsd
    $ tsc -v
    Version 1.7.5
    

    Install the web-request package and the typings definitions for Node.js...

    $ npm install web-request
    $ tsd install node
    

    Write some code...

    import * as WebRequest from 'web-request';
    (async function () {
        var result = await WebRequest.get('http://www.google.com/');
        console.log(result.content);
    })();

    Save the above to a file (index.ts), build and run it!

    $ tsc index.ts typings/node/node.d.ts --target es6 --module commonjs
    $ node index.js
    <!doctype html><html ...
    

    Response Errors as Exceptions

    The throwResponseError option will cause any response with a 400 or 500 level status to throw an exception. This option is disabled by default.

    Throw an exception for a specific request.

    await WebRequest.get('http://xyzzy.com/123', {throwResponseError: true});

    Throw an exception for any request that results in an error response.

    WebRequest.defaults({throwResponseErrors: true});

    Interface

    function get(uri: string, options?: RequestOptions): Promise<Response<string>>;
    function post(uri: string, options?: RequestOptions, content?: any): Promise<Response<string>>;
    function put(uri: string, options?: RequestOptions, content?: any): Promise<Response<string>>;
    function patch(uri: string, options?: RequestOptions, content?: any): Promise<Response<string>>;
    function head(uri: string, options?: RequestOptions): Promise<Response<void>>;
    function delete(uri: string, options?: RequestOptions): Promise<Response<string>>;
    function json<T>(uri: string, options?: RequestOptions): Promise<T>;
    function create<T>(uri: string, options?: RequestOptions, content?: any): Promise<Response<T>>;
    function stream(uri: string, options?: RequestOptions, content?: any): Promise<Response<void>>;
    function defaults(options: RequestOptions): void;
    function debug(value?: boolean): boolean;
     
    interface Request<T> extends request.Request {
        options: RequestOptions;
        response: Promise<Response<T>>;
    }
     
    class Response<T> {
        request: Request<T>;
        message: http.IncomingMessage;
        get charset(): string;
        get content(): T;  
        get contentLength(): number; 
        get contentType(): string;
        get cookies(): Cookie[];
        get headers(): Headers;
        get httpVersion(): string;
        get lastModified(): Date;    
        get method(): string;
        get server(): string;
        get statusCode(): number;
        get statusMessage(): string;        
        get uri(): Uri;
    }

    Note the following interfaces are as defined by request...

    More Examples

    Setting defaults that apply for all requests is supported...

    WebRequest.defaults({baseUrl: 'https://example.com/'});
    // now we can make requests without having to specify the root every time...
    var orders = await WebRequest.json<Order[]>('/customers/123/orders');
    await WebRequest.post('/customers/321/orders', null, orders);
    await WebRequest.delete('/customers/123');

    To make a request that requires authentication...

    await WebRequest.get('https://example.com/', {
      auth: {
        user: 'username',
        pass: 'password',
        sendImmediately: false
      }});

    To make a request with custom headers...

    await WebRequest.get('https://example.com', {headers: {'User-Agent': 'request'}});

    To enable cookies, set jar to true or specify a custom cookie jar...

    var response = await WebRequest.get('https://www.google.com/', {jar: true});
    console.log(response.cookies);

    Use the stream method to request a large resource efficiently with negligible memory impact...

    var request = WebRequest.stream('http://img15.hostingpics.net/pics/944021EarthHighRes.png'); // 4.3Mb
    var w = fs.createWriteStream('earth.png');
    request.pipe(w); // pipe content directly to a file
    var response = await request.response; // wait for web-request to complete
    await new Promise(resolve => w.on('finish', () => resolve())); // wait for file-write to complete

    Stream a file up to a server...

    var request = WebRequest.stream('http://example.com/data.json', {method:'post'});
    fs.createReadStream('file.json').pipe(request);
    await request.response;

    Stream a file from one server to another...

    var request1 = WebRequest.stream('http://test.com/earth.png', {method:'get'});
    var request2 = WebRequest.stream('http://example.com/earth.png', {method:'post'});
    request1.pipe(request2);
    await Promise.all([request1.response, request2.response]);

    Install

    npm i web-request

    DownloadsWeekly Downloads

    3,169

    Version

    1.0.7

    License

    MIT

    Last publish

    Collaborators

    • davetemplin