Source: documents/probe.js

"use strict";
/**
 @fileOverview Queries objects in memory using a mongo-like notation for reaching into objects and filtering for records

 @module documents/probe
 @author Terry Weiss
 @license MIT
 @requires lodash
 */

var sys = require( "lodash" );
/**
 The list of operators that are nested within the expression object. These take the form <code>{path:{operator:operand}}</code>
 @private
 @type {array.<string>}
 **/
var nestedOps = ["$eq", "$gt", "$gte", "$in", "$lt", "$lte", "$ne", "$nin", "$exists", "$mod", "$size", "$all"];

/**
 The list of operators that prefix the expression object. These take the form <code>{operator:{operands}}</code> or <code>{operator: [operands]}</code>
 @private
 @type {array.<string>}
 **/
var prefixOps = ["$and", "$or", "$nor", "$not"];

/**
 Processes a nested operator by picking the operator out of the expression object. Returns a formatted object that can be used for querying
 @private
 @param {string} path The path to element to work with
 @param {object} operand The operands to use for the query
 @return {object} A formatted operation definition
 **/
function processNestedOperator( path, operand ) {
	var opKeys = Object.keys( operand );
	return {
		operation : opKeys[ 0 ],
		operands  : [operand[ opKeys[ 0 ] ]],
		path      : path
	};
}

/**
 Interrogates a single query expression object and calls the appropriate handler for its contents
 @private
 @param {object} val The expression
 @param {object} key The prefix
 @returns {object} A formatted operation definition
 **/
function processExpressionObject( val, key ) {
	var operator;
	if ( sys.isObject( val ) ) {
		var opKeys = Object.keys( val );
		var op = opKeys[ 0 ];

		if ( sys.indexOf( nestedOps, op ) > -1 ) {
			operator = processNestedOperator( key, val );
		} else if ( sys.indexOf( prefixOps, key ) > -1 ) {
			operator = processPrefixOperator( key, val );
		} else if ( op === "$regex" ) {
			// special handling for regex options
			operator = processNestedOperator( key, val );
		} else if ( op === "$elemMatch" ) {
			// elemMatch is just a weird duck
			operator = {
				path      : key,
				operation : op,
				operands  : []
			};
			sys.each( val[ op ], function ( entry ) {
				operator.operands = parseQueryExpression( entry );
			} );
		}
		else {
			throw new Error( "Unrecognized operator" );
		}
	} else {
		operator = processNestedOperator( key, { $eq : val } );
	}
	return operator;
}

/**
 Processes a prefixed operator and then passes control to the nested operator method to pick out the contained values
 @private
 @param {string} operation The operation prefix
 @param {object} operand The operands to use for the query
 @return {object} A formatted operation definition
 **/
function processPrefixOperator( operation, operand ) {
	var component = {
		operation : operation,
		path      : null,
		operands  : []
	};

	if ( sys.isArray( operand ) ) {
		//if it is an array we need to loop through the array and parse each operand
		//if it is an array we need to loop through the array and parse each operand
		sys.each( operand, function ( obj ) {
			sys.each( obj, function ( val, key ) {
				component.operands.push( processExpressionObject( val, key ) );
			} );
		} );
	} else {
		//otherwise it is an object and we can parse it directly
		sys.each( operand, function ( val, key ) {
			component.operands.push( processExpressionObject( val, key ) );
		} );
	}
	return component;

}

/**
 Parses a query request and builds an object that can used to process a query target
 @private
 @param {object} obj The expression object
 @returns {object} All components of the expression in a kind of execution tree
 **/

function parseQueryExpression( obj ) {
	if ( sys.size( obj ) > 1 ) {
		var arr = sys.map( obj, function ( v, k ) {
			var entry = {};
			entry[k] = v;
			return entry;
		} );
		obj = {
			$and : arr
		};
	}
	var payload = [];
	sys.each( obj, function ( val, key ) {

		var exprObj = processExpressionObject( val, key );

		if ( exprObj.operation === "$regex" ) {
			exprObj.options = val.$options;
		}

		payload.push( exprObj );
	} );

	return payload;
}

/**
 The delimiter to use when splitting an expression
 @type {string}
 @static
 @default '.'
 **/

exports.delimiter = '.';

/**
 Splits a path expression into its component parts
 @private
 @param {string} path The path to split
 @returns {array}
 **/

function splitPath( path ) {
	return path.split( exports.delimiter );
}

/**
 Reaches into an object and allows you to get at a value deeply nested in an object
 @private
 @param {array} path The split path of the element to work with
 @param {object} record The record to reach into
 @return {*} Whatever was found in the record
 **/
function reachin( path, record ) {
	var context = record;
	var part;
	var _i;
	var _len;

	for ( _i = 0, _len = path.length; _i < _len; _i++ ) {
		part = path[_i];
		context = context[part];
		if ( sys.isNull( context ) || sys.isUndefined( context ) ) {
			break;
		}
	}

	return context;
}

/**
 This will write the value into a record at the path, creating intervening objects if they don't exist
 @private
 @param {array} path The split path of the element to work with
 @param {object} record The record to reach into
 @param {string} setter The set command, defaults to $set
 @param {object} newValue The value to write to the, or if the operator is $pull, the query of items to look for
 */
function pushin( path, record, setter, newValue ) {
	var context = record;
	var parent = record;
	var lastPart = null;
	var _i;
	var _len;
	var part;
	var keys;

	for ( _i = 0, _len = path.length; _i < _len; _i++ ) {
		part = path[_i];
		lastPart = part;
		parent = context;
		context = context[part];
		if ( sys.isNull( context ) || sys.isUndefined( context ) ) {
			parent[part] = {};
			context = parent[part];
		}
	}

	if ( sys.isEmpty( setter ) || setter === '$set' ) {
		parent[lastPart] = newValue;
		return parent[lastPart];
	} else {
		switch ( setter ) {
			case '$inc':
				/**
				 * Increments a field by the amount you specify. It takes the form
				 * `{ $inc: { field1: amount } }`
				 * @name $inc
				 * @memberOf module:documents/probe.updateOperators
				 * @example
				 * var probe = require("documents/probe");
				 * probe.update( obj, {'name.last' : 'Owen', 'name.first' : 'LeRoy'},
				 * {$inc : {'password.changes' : 2}} );
				 */

				if ( !sys.isNumber( newValue ) ) {
					newValue = 1;
				}
				if ( sys.isNumber( parent[lastPart] ) ) {
					parent[lastPart] = parent[lastPart] + newValue;
					return parent[lastPart];
				}
				break;
			case '$dec':
				/**
				 * Decrements a field by the amount you specify. It takes the form
				 * `{ $dec: { field1: amount }`
                 * @name $dec
				 * @memberOf module:documents/probe.updateOperators
				 * @example
				 *  var probe = require("documents/probe");
				 * probe.update( obj, {'name.last' : 'Owen', 'name.first' : 'LeRoy'},
				 * {$dec : {'password.changes' : 2}} );
				 */

				if ( !sys.isNumber( newValue ) ) {
					newValue = 1;
				}
				if ( sys.isNumber( parent[lastPart] ) ) {
					parent[lastPart] = parent[lastPart] - newValue;
					return parent[lastPart];
				}
				break;
			case '$unset':
				/**
				 * Removes the field from the object. It takes the form
				 * `{ $unset: { field1: "" } }`
				 * @name $unset
				 * @memberOf module:documents/probe.updateOperators
				 * @example
				 * var probe = require("documents/probe");
				 * probe.update( data, {'name.first' : 'Yogi'}, {$unset : {'name.first' : ''}} );
				 */

				return delete parent[lastPart];
			case '$pop':
				/**
				 * The $pop operator removes the first or last element of an array. Pass $pop a value of 1 to remove the last element
				 * in an array and a value of -1 to remove the first element of an array. This will only work on arrays. Syntax:
				 * `{ $pop: { field: 1 } }` or `{ $pop: { field: -1 } }`
				 * @name $pop
				 * @memberOf module:documents/probe.updateOperators
				 * @example
				 * var probe = require("documents/probe");
				 * // attr is the name of the array field
				 * probe.update( data, {_id : '511d18827da2b88b09000133'}, {$pop : {attr : 1}} );
				 */

				if ( sys.isArray( parent[lastPart] ) ) {
					if ( !sys.isNumber( newValue ) ) {
						newValue = 1;
					}
					if ( newValue === 1 ) {
						return parent[lastPart].pop();
					} else {
						return parent[lastPart].shift();
					}
				}
				break;
			case '$push':
				/**
				 * The $push operator appends a specified value to an array. It looks like this:
				 * `{ $push: { <field>: <value> } }`
				 * @name $push
				 * @memberOf module:documents/probe.updateOperators
				 * @example
				 * var probe = require("documents/probe");
				 * // attr is the name of the array field
				 * probe.update( data, {_id : '511d18827da2b88b09000133'},
				 * {$push : {attr : {"hand" : "new", "color" : "new"}}} );
				 */

				if ( sys.isArray( parent[lastPart] ) ) {
					return parent[lastPart].push( newValue );
				}
				break;
			case '$pull':
				/**
				 * The $pull operator removes all instances of a value from an existing array. It looks like this:
				 * `{ $pull: { field: <query> } }`
				 * @name $pull
				 * @memberOf module:documents/probe.updateOperators
				 * @example
				 * var probe = require("documents/probe");
				 * // attr is the name of the array field
				 * probe.update( data, {'email' : 'EWallace.43@fauxprisons.com'},
				 * {$pull : {attr : {"color" : "green"}}} );
				 */

				if ( sys.isArray( parent[lastPart] ) ) {
					keys = exports.findKeys( parent[lastPart], newValue );
					sys.each( keys, function ( val, index ) {
						return delete parent[lastPart][index];
					} );
					parent[lastPart] = sys.compact( parent[lastPart] );
					return parent[lastPart];
				}
		}
	}
}

/**
 The query operations that evaluate directly from an operation
 @private
 **/
var operations = {
	/**
	 * `$eq` performs a `===` comparison by comparing the value directly if it is an atomic value.
	 * otherwise if it is an array, it checks to see if the value looked for is in the array.
	 * `{field: value}` or `{field: {$eq : value}}` or `{array: value}` or `{array: {$eq : value}}`
	 * @name $eq
	 * @memberOf module:documents/probe.queryOperators
	 * @example
	 * var probe = require("documents/probe");
	 * probe.find( data, {categories : "cat1"} );
	 * // is the same as
	 * probe.find( data, {categories : {$eq: "cat1"}} );
	 */

	$eq        : function ( qu, value ) {
		if ( sys.isArray( value ) ) {
			return sys.find( value, function ( entry ) {
				return JSON.stringify( qu.operands[0] ) === JSON.stringify( entry );
			} ) !== void 0;
		} else {
			return JSON.stringify( qu.operands[0] ) === JSON.stringify( value );
		}
	},
	/**
	 *  `$ne` performs a `!==` comparison by comparing the value directly if it is an atomic value. Otherwise, if it is an array
	 * this is performs a "not in array".
	 * '{field: {$ne : value}}` or '{array: {$ne : value}}`
	 * @name $ne
	 * @memberOf module:documents/probe.queryOperators
	 * @example
	 * var probe = require("documents/probe");
	 * probe.find( data, {"name.first" : {$ne : "Sheryl"}} );
	 */

	$ne        : function ( qu, value ) {
		if ( sys.isArray( value ) ) {
			return sys.find( value, function ( entry ) {
				return JSON.stringify( qu.operands[0] ) !== JSON.stringify( entry );
			} ) !== void 0;
		} else {
			return JSON.stringify( qu.operands[0] ) !== JSON.stringify( value );
		}
	},
	/**
	 * `$all` checks to see if all of the members of the query are included in an array
	 * `{array: {$all: [val1, val2, val3]}}`
	 * @name $all
	 * @memberOf module:documents/probe.queryOperators
	 * @example
	 * var probe = require("documents/probe");
	 * probe.find( data, {"categories" : {$all : ["cat4", "cat2", "cat1"]}} );
	 */

	$all       : function ( qu, value ) {
		var operands, result;

		result = false;
		if ( sys.isArray( value ) ) {
			operands = sys.flatten( qu.operands );
			result = sys.intersection( operands, value ).length === operands.length;
		}
		return result;
	},
	/**
	 * `$gt` Sees if a field is greater than the value
	 * `{field: {$gt: value}}`
	 * @name $gt
	 * @memberOf module:documents/probe.queryOperators
	 * @example
	 * var probe = require("documents/probe");
	 * probe.find( data, {"age" : {$gt : 24}} );
	 */

	$gt        : function ( qu, value ) {
		return qu.operands[0] < value;
	},
	/**
	 * `$gte` Sees if a field is greater than or equal to the value
	 * `{field: {$gte: value}}`
	 * @name $gte
	 * @memberOf module:documents/probe.queryOperators
	 * @example
	 * var probe = require("documents/probe");
	 * probe.find( data, {"age" : {$gte : 50}} );
	 */

	$gte       : function ( qu, value ) {
		return qu.operands[0] <= value;
	},
	/**
	 * `$lt` Sees if a field is less than the value
	 * `{field: {$lt: value}}`
	 * @name $lt
	 * @memberOf module:documents/probe.queryOperators
	 * @example
	 * var probe = require("documents/probe");
	 * probe.find( data, {"age" : {$lt : 24}} );
	 */

	$lt        : function ( qu, value ) {
		return qu.operands[0] > value;
	},
	/**
	 * `$lte` Sees if a field is less than or equal to the value
	 * `{field: {$lte: value}}`
	 * @name $lte
	 * @memberOf module:documents/probe.queryOperators
	 * @example
	 * var probe = require("documents/probe");
	 * probe.find( data, {"age" : {$lte : 50}} );
	 */

	$lte       : function ( qu, value ) {
		return qu.operands[0] >= value;
	},
	/**
	 * `$in` Sees if a field has one of the values in the query
	 * `{field: {$in: [test1, test2, test3,...]}}`
	 * @name $in
	 * @memberOf module:documents/probe.queryOperators
	 * @example
	 * var probe = require("documents/probe");
	 * probe.find( data, {"age" : {$in : [24, 28, 60]}} );
	 */

	$in        : function ( qu, value ) {
		var operands;

		operands = sys.flatten( qu.operands );
		return sys.indexOf( operands, value ) > -1;
	},
	/**
	 * `$nin` Sees if a field has none of the values in the query
	 * `{field: {$nin: [test1, test2, test3,...]}}`
	 * @name $nin
	 * @memberOf module:documents/probe.queryOperators
	 * @example
	 * var probe = require("documents/probe");
	 * probe.find( data, {"age" : {$nin : [24, 28, 60]}} );
	 */

	$nin       : function ( qu, value ) {
		var operands;

		operands = sys.flatten( qu.operands );
		return sys.indexOf( operands, value ) === -1;
	},
	/**
	 * `$exists` Sees if a field exists.
	 * `{field: {$exists: true|false}}`
	 * @name $exists
	 * @memberOf module:documents/probe.queryOperators
	 * @example
	 * var probe = require("documents/probe");
	 * probe.find( data, {"name.middle" : {$exists : true}} );
	 */

	$exists    : function ( qu, value ) {
		return (sys.isNull( value ) || sys.isUndefined( value )) !== qu.operands[0];
	},
	/**
	 * Checks equality to a modulus operation on a field
	 * `{field: {$mod: [divisor, remainder]}}`
	 * @name $mod
	 * @memberOf module:documents/probe.queryOperators
	 * @example
	 * var probe = require("documents/probe");
	 * probe.find( data, {"age" : {$mod : [2, 0]}} );
	 */

	$mod       : function ( qu, value ) {
		var operands = sys.flatten( qu.operands );
		if ( operands.length !== 2 ) {
			throw new Error( "$mod requires two operands" );
		}
		var mod = operands[0];
		var rem = operands[1];
		return value % mod === rem;
	},
	/**
	 * Compares the size of the field/array to the query. This can be used on arrays, strings and objects (where it will count keys)
	 * `{'field|array`: {$size: value}}`
	 * @name $size
	 * @memberOf module:documents/probe.queryOperators
	 * @example
	 * var probe = require("documents/probe");
	 * probe.find( data, {attr : {$size : 3}} );
	 */

	$size      : function ( qu, value ) {
		return sys.size( value ) === qu.operands[0];
	},
	/**
	 * Performs a regular expression test againts the field
	 * `{field: {$regex: re, $options: reOptions}}`
	 * @name $regex
	 * @memberOf module:documents/probe.queryOperators
	 * @example
	 * var probe = require("documents/probe");
	 * probe.find( data, {"name.first" : {$regex : "m*", $options : "i"}} );
	 */

	$regex     : function ( qu, value ) {
		var r = new RegExp( qu.operands[0], qu.options );
		return r.test( value );
	},
	/**
	 * This is like $all except that it works with an array of objects or value. It checks to see the array matches all
	 * of the conditions of the query
	 * `{array: {$elemMatch: {path: value, path: {$operation: value2}}}`
     * @name $elemMatch
	 * @memberOf module:documents/probe.queryOperators
	 * @example
	 * var probe = require("documents/probe");
	 * probe.find( data, {attr : {$elemMatch : [
     *  {color : "red", "hand" : "left"}
     * ]}} );
	 */
	$elemMatch : function ( qu, value ) {
		var expression, test, _i, _len;

		if ( sys.isArray( value ) ) {
			var _ref = qu.operands;
			for ( _i = 0, _len = _ref.length; _i < _len; _i++ ) {
				expression = _ref[_i];
				if ( expression.path ) {
					expression.splitPath = splitPath( expression.path );
				}
			}
			test = execQuery( value, qu.operands, null, true ).arrayResults;
		}
		return test.length > 0;
	},
	/**
	 * Returns true if all of the conditions of the query are met
	 * `{$and: [query1, query2, query3]}`
	 * @name $and
	 * @memberOf module:documents/probe.queryOperators
	 * @example
	 * var probe = require("documents/probe");
	 * probe.find( data, {$and : [
     *      {"name.first" : "Mildred"},
     *      {"name.last" : "Graves"}
     * ]} );
	 */

	$and       : function ( qu, value, record ) {
		var isAnd = false;

		sys.each( qu.operands, function ( expr ) {
			if ( expr.path ) {
				expr.splitPath = expr.splitPath || splitPath( expr.path );
			}
			var test = reachin( expr.splitPath, record, expr.operation );
			isAnd = operations[expr.operation]( expr, test, record );
			if ( !isAnd ) {
				return false;
			}
		} );

		return isAnd;
	},
	/**
	 * Returns true if any of the conditions of the query are met
	 * `{$or: [query1, query2, query3]}`
	 * @name $or
	 * @memberOf module:documents/probe.queryOperators
	 * @example
	 * var probe = require("documents/probe");
	 * probe.find( data, {$or : [
     *      "age" : {$in : [24, 28, 60]}},
	 *      {categories : "cat1"}
	 * ]} );
	 */
	$or        : function ( qu, value, record ) {
		var isOr = false;
		sys.each( qu.operands, function ( expr ) {
			if ( expr.path ) {
				expr.splitPath = expr.splitPath || splitPath( expr.path );
			}
			var test = reachin( expr.splitPath, record, expr.operation );
			isOr = operations[expr.operation]( expr, test, record );
			if ( isOr ) {
				return false;
			}
		} );

		return isOr;
	},
	/**
	 * Returns true if none of the conditions of the query are met
	 * `{$nor: [query1, query2, query3]}`
	 * @name $nor
	 * @memberOf module:documents/probe.queryOperators
	 * @example
	 * var probe = require("documents/probe");
	 * probe.find( data, {$nor : [
     *      {"age" : {$in : [24, 28, 60]}},
     *      {categories : "cat1"}
     * ]} );
	 */
	$nor       : function ( qu, value, record ) {
		var isOr = false;
		sys.each( qu.operands, function ( expr ) {
			if ( expr.path ) {
				expr.splitPath = expr.splitPath || splitPath( expr.path );
			}
			var test = reachin( expr.splitPath, record, expr.operation );
			isOr = operations[expr.operation]( expr, test, record );
			if ( isOr ) {
				return false;
			}
		} );

		return !isOr;
	},
	/**
	 * Logical NOT on the conditions of the query
	 * `{$not: [query1, query2, query3]}`
	 * @name $not
	 * @memberOf module:documents/probe.queryOperators
	 * @example
	 * var probe = require("documents/probe");
	 * probe.find( data, {$not : {"age" : {$lt : 24}}} );
	 */
	$not       : function ( qu, value, record ) {

		var result = false;
		sys.each( qu.operands, function ( expr ) {
			if ( expr.path ) {
				expr.splitPath = expr.splitPath || splitPath( expr.path );
			}
			var test = reachin( expr.splitPath, record, expr.operation );
			result = operations[expr.operation]( expr, test, record );
			if ( result ) {
				return false;
			}
		} );

		return !result;

	}
};

/**
 Executes a query by traversing a document and evaluating each record
 @private
 @param {array|object} obj The object to query
 @param {object} qu The query to execute
 @param {?boolean} shortCircuit When true, the condition that matches the query stops evaluation for that record, otherwise all conditions have to be met
 @param {?boolean} stopOnFirst When true all evaluation stops after the first record is found to match the conditons
 **/
function execQuery( obj, qu, shortCircuit, stopOnFirst ) {
	var arrayResults = [];
	var keyResults = [];
	sys.each( obj, function ( record, key ) {
		var expr, result, test, _i, _len;

		for ( _i = 0, _len = qu.length; _i < _len; _i++ ) {
			expr = qu[_i];
			if ( expr.splitPath ) {
				test = reachin( expr.splitPath, record, expr.operation );
			}
			result = operations[expr.operation]( expr, test, record );
			if ( result ) {
				arrayResults.push( record );
				keyResults.push( key );
			}
			if ( !result && shortCircuit ) {
				break;
			}
		}
		if ( arrayResults.length > 0 && stopOnFirst ) {
			return false;
		}
	} );
	return {
		arrayResults : arrayResults,
		keyResults   : keyResults
	};
}

/**
 Updates all records in obj that match the query. See {@link module:documents/probe.updateOperators} for the operators that are supported.
 @param {object|array} obj The object to update
 @param {object} qu The query which will be used to identify the records to updated
 @param {object} setDocument The update operator. See {@link module:documents/probe.updateOperators}
 */
exports.update = function ( obj, qu, setDocument ) {
	var records = exports.find( obj, qu );
	return sys.each( records, function ( record ) {
		return sys.each( setDocument, function ( fields, operator ) {
			return sys.each( fields, function ( newValue, path ) {
				return pushin( splitPath( path ), record, operator, newValue );
			} );
		} );
	} );
};
/**
 Find all records that match a query
 @param {array|object} obj The object to query
 @param {object} qu The query to execute. See {@link module:documents/probe.queryOperators} for the operators you can use.
 @returns {array} The results
 **/
exports.find = function ( obj, qu ) {
	var expression, _i, _len;

	var query = parseQueryExpression( qu );
	for ( _i = 0, _len = query.length; _i < _len; _i++ ) {
		expression = query[_i];
		if ( expression.path ) {
			expression.splitPath = splitPath( expression.path );
		}
	}
	return execQuery( obj, query ).arrayResults;
};
/**
 Find all records that match a query and returns the keys for those items. This is similar to {@link module:documents/probe.find} but instead of returning
 records, returns the keys. If `obj` is an object it will return the hash key. If 'obj' is an array, it will return the index
 @param {array|object} obj The object to query
 @param {object} qu The query to execute. See {@link module:documents/probe.queryOperators} for the operators you can use.
 @returns {array}
 */
exports.findKeys = function ( obj, qu ) {
	var expression, _i, _len;

	var query = parseQueryExpression( qu );
	for ( _i = 0, _len = query.length; _i < _len; _i++ ) {
		expression = query[_i];
		if ( expression.path ) {
			expression.splitPath = splitPath( expression.path );
		}
	}
	return execQuery( obj, query ).keyResults;
};

/**
 Returns the first record that matches the query. Aliased as `seek`.
 @param {array|object} obj The object to query
 @param {object} qu The query to execute. See {@link module:documents/probe.queryOperators} for the operators you can use.
 @returns {object}
 */
exports.findOne = function ( obj, qu ) {
	var expression, _i, _len;

	var query = parseQueryExpression( qu );
	for ( _i = 0, _len = query.length; _i < _len; _i++ ) {
		expression = query[_i];
		if ( expression.path ) {
			expression.splitPath = splitPath( expression.path );
		}
	}
	var results = execQuery( obj, query, false, true ).arrayResults;
	if ( results.length > 0 ) {
		return results[0];
	} else {
		return null;
	}
};
exports.seek = exports.findOne;
/**
 Returns the first record that matches the query and returns its key or index depending on whether `obj` is an object or array respectively.
 Aliased as `seekKey`.
 @param {array|object} obj The object to query
 @param {object} qu The query to execute. See {@link module:documents/probe.queryOperators} for the operators you can use.
 @returns {object}
 */
exports.findOneKey = function ( obj, qu ) {
	var expression, _i, _len;

	var query = parseQueryExpression( qu );
	for ( _i = 0, _len = query.length; _i < _len; _i++ ) {
		expression = query[_i];
		if ( expression.path ) {
			expression.splitPath = splitPath( expression.path );
		}
	}
	var results = execQuery( obj, query, false, true ).keyResults;
	if ( results.length > 0 ) {
		return results[0];
	} else {
		return null;
	}
};
exports.seekKey = exports.findOneKey;

/**
 Remove all items in the object/array that match the query
 @param {array|object} obj The object to query
 @param {object} qu The query to execute. See {@link module:documents/probe.queryOperators} for the operators you can use.
 @return {object|array} The array or object as appropriate without the records.
 **/
exports.remove = function ( obj, qu ) {
	var expression, _i, _len;

	var query = parseQueryExpression( qu );
	for ( _i = 0, _len = query.length; _i < _len; _i++ ) {
		expression = query[_i];
		if ( expression.path ) {
			expression.splitPath = splitPath( expression.path );
		}
	}
	var results = execQuery( obj, query, false, false ).keyResults;
	if ( sys.isArray( obj ) ) {
		var newArr = [];
		sys.each( obj, function ( item, index ) {
			if ( sys.indexOf( results, index ) === -1 ) {
				return newArr.push( item );
			}
		} );
		return newArr;
	} else {
		sys.each( results, function ( key ) {
			return delete obj[key];
		} );
		return obj;
	}
};
/**
 Returns true if all items match the query

 @param {array|object} obj The object to query
 @param {object} qu The query to execute. See {@link module:documents/probe.queryOperators} for the operators you can use.
 @returns {boolean}
 **/
exports.all = function ( obj, qu ) {
	return exports.find( obj, qu ).length === sys.size( obj );
};

/**
 Returns true if any of the items match the query

 @param {array|object} obj The object to query
 @param {object} qu The query to execute. See {@link module:documents/probe.queryOperators} for the operators you can use.
 @returns {boolean}
 **/
exports.any = function ( obj, qu ) {
	var expression, _i, _len;

	var query = parseQueryExpression( qu );
	for ( _i = 0, _len = query.length; _i < _len; _i++ ) {
		expression = query[_i];
		if ( expression.path ) {
			expression.splitPath = splitPath( expression.path );
		}
	}
	var results = execQuery( obj, query, true, true ).keyResults;
	return results.length > 0;
};

/**
 Returns the set of unique records that match a query
 @param {array|object} obj The object to query
 @param {object} qu The query to execute. See {@link module:documents/probe.queryOperators} for the operators you can use.
 @return {array}
 **/
exports.unique = function ( obj, qu ) {
	var test = exports.find( obj, qu );
	return sys.unique( test, function ( item ) {
		return JSON.stringify( item );
	} );
};

/**
 This will write the value into a record at the path, creating intervening objects if they don't exist. This does not work as filtered
 update and is meant to be used on a single record. It is a nice way of setting a property at an arbitrary depth at will.

 @param {array} path The split path of the element to work with
 @param {object} record The record to reach into
 @param {string} setter The set operation.  See {@link module:documents/probe.updateOperators} for the operators you can use.
 @param {object} newValue The value to write to the, or if the operator is $pull, the query of items to look for
 */
exports.set = function ( record, path, setter, newValue ) {
	return pushin( splitPath( path ), record, setter, newValue );
};

/**
 Reaches into an object and allows you to get at a value deeply nested in an object. This is not a query, but a
 straight reach in, useful for event bindings

 @param {array} path The split path of the element to work with
 @param {object} record The record to reach into
 @return {*} Whatever was found in the record
 **/
exports.get = function ( record, path ) {
	return reachin( splitPath( path ), record );
};

/**
 Returns true if any of the items match the query. Aliases as `any`
 @function
 @param {array|object} obj The object to query
 @param {object} qu The query to execute
 @returns {boolean}
 */
exports.some = exports.any;

/**
 Returns true if all items match the query. Aliases as `all`
 @function
 @param {array|object} obj The object to query
 @param {object} qu The query to execute
 @returns {boolean}
 */
exports.every = exports.all;

var bindables = {
	any        : exports.any,
	all        : exports.all,
	remove     : exports.remove,
	seekKey    : exports.seekKey,
	seek       : exports.seek,
	findOneKey : exports.findOneKey,
	findOne    : exports.findOne,
	findKeys   : exports.findKeys,
	find       : exports.find,
	update     : exports.update,
	some       : exports.some,
	every      : exports.every,
	"get"      : exports.get,
	"set"      : exports.set
};

/**
 Binds the query and update methods to a new object. When called these
 methods can skip the first parameter so that find(object, query) can just be called as find(query)
 @param {object|array} obj The object or array to bind to
 @return {object} An object with method bindings in place
 **/
exports.proxy = function ( obj ) {
	var retVal;

	retVal = {};
	sys.each( bindables, function ( val, key ) {
		retVal[key] = sys.bind( val, obj, obj );
	} );
	return retVal;
};

/**
 Binds the query and update methods to a specific object and adds the methods to that object. When called these
 methods can skip the first parameter so that find(object, query) can just be called as object.find(query)
 @param {object|array} obj The object or array to bind to
 @param {object|array=} collection If the collection is not the same as <code>this</code> but is a property, or even
 a whole other object, you specify that here. Otherwise the <code>obj</code> is assumed to be the same as the collecion
 **/
exports.mixin = function ( obj, collection ) {
	collection = collection || obj;
	return sys.each( bindables, function ( val, key ) {
		obj[key] = sys.bind( val, obj, collection );
	} );
};

/**
 * These are the supported query operators
 *
 * @memberOf module:documents/probe
 * @name queryOperators
 * @class This is not actually a class, but an artifact of the documentation system
 */

/**
 * These are the supported update operators
 *
 * @memberOf module:documents/probe
 * @name updateOperators
 * @class This is not actually a class, but an artifact of the documentation system
 */