yql-client/yql.js

Nodejs client lib for the Yahoo YQL service.

/*jshint multistr:true */

var http = require('http'),
    https = require('https');

/**
 * Utility Class used under the hood by the YQL class
 * @class YQLRequest
 * @constructor
 * @param {String} sql The SQL statement to execute
 * @param {Function/Object} callback The callback to execute after the query
 * @param {Object} params An object literal of extra parameters to pass along (optional).
 * @param {Object} opts An object literal of configuration options (optional): proto (http|https), base (url)
 */
var YQLRequest = function (sql, callback, params, opts) {

    if (!params) {
        params = {};
    }
    params.q = sql;
    //Allow format override.. JSON-P-X
    if (!params.format) {
        params.format = YQLRequest.FORMAT;
    }
    if (!params.env) {
        params.env = YQLRequest.ENV;
    }

    this._context = this;

    if (opts && opts.context) {
        this._context = opts.context;
        delete opts.context;
    }

    if (params && params.context) {
        this._context = params.context;
        delete params.context;
    }

    this._params = params;
    this._opts = opts;
    this._callback = callback;

};

YQLRequest.prototype = {
    /**
    * @private
    * @property _jsonp
    * @description Reference to the JSONP instance used to make the queries
    */
    _jsonp: null,
    /**
    * @private
    * @property _opts
    * @description Holder for the opts argument
    */
    _opts: null,
    /**
    * @private
    * @property _callback
    * @description Holder for the callback argument
    */
    _callback: null,
    /**
    * @private
    * @property _params
    * @description Holder for the params argument
    */
    _params: null,
    /**
    * @private
    * @property _context
    * @description The context to execute the callback in
    */
    _context: null,
    /**
    * @private
    * @method _internal
    * @description Internal Callback Handler
    */
    _internal: function () {
        this._callback.apply(this._context, arguments);
    },
    /**
    * @method send
    * @description The method that executes the YQL Request.
    * @chainable
    * @return {YQLRequest}
    */
    send: function () {
        var qs = [], url = ((this._opts && this._opts.proto) ? this._opts.proto : YQLRequest.PROTO), o, key, hasOwn = Object.prototype.hasOwnProperty;

        for (key in this._params) {
            if (hasOwn.call(this._params, key)) {
                var value = this._params[key];
                qs.push(key + '=' + encodeURIComponent(value));
            }
        }

        qs = qs.join('&');

        url += ((this._opts && this._opts.base) ? this._opts.base : YQLRequest.BASE_URL) + qs;

        o = (typeof this._callback !== 'function') ? this._callback : { on: { success: this._callback } };

        o.on = o.on || {};
        this._callback = o.on.success;

        o.on.success = this._internal.bind(this);
        this._send(url, o);
        return this;
    },
    /**
    * Private method to send the request, overwritten in plugins
    * @method _send
    * @private
    * @param {String} url The URL to request
    * @param {Object} o The config object
    */
    _send: function() {
        //Overwritten in plugins
    }
};

/**
* @static
* @property FORMAT
* @description Default format to use: json
*/
YQLRequest.FORMAT = 'json';
/**
* @static
* @property PROTO
* @description Default protocol to use: http
*/
YQLRequest.PROTO = 'http';
/**
* @static
* @property BASE_URL
* @description The base URL to query: query.yahooapis.com/v1/public/yql?
*/
YQLRequest.BASE_URL = ':/' + '/query.yahooapis.com/v1/public/yql?';
/**
* @static
* @property ENV
* @description The environment file to load: http://datatables.org/alltables.env
*/
YQLRequest.ENV = 'http:/' + '/datatables.org/alltables.env';

//Over writes Y.YQLRequest._send to use request instead of JSONP
YQLRequest.prototype._send = function (url, o) {
    var reqProtocol = url.indexOf('https://') > -1 ? https : http;
    reqProtocol.get(url, function(res) {
        var data = '';
        res.setEncoding('utf8');
        res.on('data', function (chunk) {
            data += chunk;
        });

        res.on('end', function() {
            o.on.success(JSON.parse(data));
        });

    }).on('error', function(e){
        //The signature that YQL requires
        o.on.success({
            error: e
        });
    }).setTimeout((o.timeout || (30 * 1000)), function(){

        o.on.success({
            error: 'request timed out'
        });

        this.destroy();
    });
};

/**
 * This class adds a sugar class to allow access to YQL (http://developer.yahoo.com/yql/).
 * @class YQL
 * @constructor
 * @param {String} sql The SQL statement to execute
 * @param {Function} callback The callback to execute after the query (optional).
 * @param {Object} params An object literal of extra parameters to pass along (optional).
 * @param {Object} opts An object literal of configuration options (optional): proto (http|https), base (url)
 */
var YQL = function (sql, callback, params, opts) {
    return new YQLRequest(sql, callback, params, opts).send();
};

module.exports = {YQL: YQL, YQLRequest: YQLRequest};