lib/dataset/actions.js
function (args) {
            args = comb(arguments).toArray();
            var cb,
                block = isFunction(args[args.length - 1]) ? args.pop() : null;
            if (block && block.length > 0) {
                cb = block;
                block = isFunction(args[args.length - 1]) ? args.pop() : null;
            }

            var ds = block ? this.filter(block) : this;
            if (!args.length) {
                return ds.singleRecord(cb);
            } else {
                args = (args.length === 1) ? args[0] : args;
                if (isNumber(args)) {
                    return ds.limit(args).all(null, cb);
                } else {
                    return ds.filter(args).singleRecord(cb);
                }
            }
        }
function (args) {
            args = comb(arguments).toArray();
            var cb,
                block = isFunction(args[args.length - 1]) ? args.pop() : null;
            if (block && block.length > 0) {
                cb = block;
                block = isFunction(args[args.length - 1]) ? args.pop() : null;
            }

            var ds = block ? this.filter(block) : this;
            if (!args.length) {
                return ds.singleRecord(cb);
            } else {
                args = (args.length === 1) ? args[0] : args;
                if (isNumber(args)) {
                    return ds.limit(args).all(null, cb);
                } else {
                    return ds.filter(args).singleRecord(cb);
                }
            }
        }
function ( args ) { args = comb ( arguments ) . toArray ( ) ; var cb , block = isFunction ( args [ args . length - 1 ] ) ? args . pop ( ) : null ; if ( block && block . length > 0 ) { cb = block ; block = isFunction ( args [ args . length - 1 ] ) ? args . pop ( ) : null ; } var ds = block ? this . filter ( block ) : this ; if ( ! args . length ) { return ds . singleRecord ( cb ) ; } else { args = ( args . length === 1 ) ? args [ 0 ] : args ; if ( isNumber ( args ) ) { return ds . limit ( args ) . all ( null , cb ) ; } else { return ds . filter ( args ) . singleRecord ( cb ) ; } } }
If a integer argument is given, it is interpreted as a limit, and then returns all
matching records up to that limit.

If no arguments are passed, it returns the first matching record.

If a function taking no arguments is passed in as the last parameter then it
is assumed to be a filter block. If the a funciton is passed in that takes arguments
then it is assumed to be a callback. You may also pass in both the second to last argument
being a filter function, and the last being a callback.

If any other type of argument(s) is passed, it is given to {@link patio.Dataset#filter} and the
first matching record is returned.  Examples:

@example

comb.executeInOrder(DB.from("table"), function(ds){
// SELECT * FROM table LIMIT 1
ds.first(); // => {id : 7}

// SELECT * FROM table LIMIT 2
ds.first(2); // => [{id : 6}, {id : 4}]

// SELECT * FROM table WHERE (id = 2) LIMIT 1
ds.first({id : 2}) // => {id : 2}


// SELECT * FROM table WHERE (id = 3) LIMIT 1
ds.first("id = 3"); // => {id : 3}

// SELECT * FROM table WHERE (id = 4) LIMIT 1
ds.first("id = ?", 4); // => {id : 4}

// SELECT * FROM table WHERE (id > 2) LIMIT 1
ds.first(function(){return this.id.gt(2);}); // => {id : 5}


// SELECT * FROM table WHERE ((id > 4) AND (id < 6)) LIMIT 1
ds.first("id > ?", 4, function(){
return this.id.lt(6);
}); // => {id : 5}

// SELECT * FROM table WHERE (id < 2) LIMIT 2
ds.first(2, function(){
return this.id.lt(2)
}); // => [{id:1}]
});

@param {*} args varargs to be used to limit/filter the result set.

@return {comb.Promise} a promise that is resolved with the either the first matching record.
Or an array of items if a limit was provided as the first argument.
If a integer argument is given it is interpreted as a limit and then returns all matching records up to that limit .