query.js is for your Sphere game. Use it to zip through arrays of data in little time with little effort. Useful for battle systems, person management, and menus.

query.js

/**
* Script: query.js
* Written by: Radnen
* Updated: 12/28/2013
**/

var Query = {
	results: [],
	
	/*
		A getter for the results length.
	*/
	get length() {
		return this.results.length;
	},

	/*
		Setup the original array to query from.
	*/
	from: function(array) {
		this.results = array;
		return this;
	},
	
	/*
		Search for objects that satisfy a condition
		and put them into a results array.
	*/
	where: function(comp) {
		if (typeof comp != "function") Abort("QueryError: not a valid Function for Query.where().");
		var array = [];
		
		for (var i = 0, l = this.results.length; i < l; ++i) {
			if (comp(this.results[i])) array.push(this.results[i]);
		}
		
		this.results = array;
		return this;
	},
	
	/*
		Return the first result or the first
		result accepted by the predicate function.
	*/
	first: function(func) {
		if (typeof func != "function") return this.results[0];
		else {
			for (var i = 0, l = this.results.length; i < l; ++i)
				if (func(this.results[i])) return this.results[i];
			return null;
		}
	},
	
	/*
		Return the last item in the list.
	*/
	last: function() {
		return this.results[this.results.length - 1];
	},
	
	/*
		Shortens the array to the desired size.
	*/
	prune: function(size) {
		if (size >= this.results.length) return this;
		this.results.splice(size, this.results.length);
		return this;
	},
	
	/*
		Get a particular item in the list.
	*/
	get: function(i) {
		return this.results[i];
	},
	
	/*
		Get a random item from the results list.
	*/
	random: function() {
		var index = Math.floor(Math.random() * this.results.length);
		return this.results[index];
	},
	
	/*
		Returns true if we found anything at all.
	*/
	exists: function() {
		return this.results.length > 0;
	},
	
	/*
		Grabs the size of the underlying results array. See length getter.
	*/
	size: function() {
		return this.results.length;
	},
	
	/*
		Returns the entire results array.
	*/
	all: function() {
		return this.results;
	},
	
	/*
		Returns and removes first item from results list.
	*/
	shift: function() {
		return this.results.shift();
	},

	/*
		Returns and removes the last item from results list.
	*/
	pop: function() {
		return this.results.pop();
	},
	
	/*
		Removes a particular item from the list and returns it.
	*/
	removeAt: function(index) {
		if (index < 0 || index >= this.results.length) return null;
		var item = this.results[index];
		this.results.splice(index, 1);
		return item;
	},

	/*
		Sorts the results list.
	*/
	sort: function(f) {
		if (typeof f == "function") this.results.sort(f);
		else this.results.sort();
		return this;
	},
	
	/*
		Applies a function to each object in the results list.
	*/
	foreach: function(func, scope) {
		if (typeof func != "function") Abort("QueryError: not a valid Function for Query.foreach().");
		
		for (var i = 0, l = this.results.length; i < l; ++i) {
			func.call(scope, this.results[i], i, this.results);
		}
		
		return this;
	},
	
	/*
		Modifies each result in the results list through a function.
	*/
	map: function(func, scope) {
		if (typeof func != "function") Abort("QueryError: not a valid Function for Query.map().");

		for (var i = 0, l = this.results.length; i < l; ++i) {
			this.results[i] = func.call(scope, this.results[i], i, this.results);
		}
		
		return this;
	},
	
	/*
		Returns true if the predicate is accepted by the results list.
	*/
	contains: function(func, scope) {
		if (typeof func != "function") Abort("QueryError: not a valid Function for Query.contains().");
		
		for (var i = 0, l = this.results.length; i < l; ++i) {
			if (func.call(scope, this.results[i], i, this.results)) return true;
		}
		
		return false;
	},
	
	/*
		Adds a stored procedure: just like using 'where' but with a predefined predicate and arguments.
	*/
	addProcedure: function(name, func) {
		if (name in this) Abort("QueryError: \"" + name + "\" already a procedure.");
		this[name] = function() {
			var array = [], args = [];
			
			for (var i = 0, l = arguments.length; i < l; i++) {
				args[i + 1] = arguments[i];
			}
			
			for (var i = 0, l = this.results.length; i < l; ++i) {
				args[0] = this.results[i];
				if (func.apply(null, args)) array.push(this.results[i]);
			}
			
			this.results = array;
			return this;
		}.bind(this);
	}
}