forerunnerdb v2.0.22

ForerunnerDB - A NoSQL JSON Document DB

ForerunnerDB is developed with ❤ love by Irrelon Software Limited, a UK registered company.

ForerunnerDB is used in live projects that serve millions of users a day, is production ready and battle tested in real-world applications.

ForerunnerDB receives no funding or third-party backing except from patrons like yourself. If you love ForerunnerDB and want to support its development, or if you use it in your own products please consider becoming a patron: https://www.patreon.com/user?u=4443427

Community Support: https://github.com/Irrelon/ForerunnerDB/issues Commercial Support: forerunnerdb@irrelon.com

Version 2.0.22

TravisCI Build Test Status

Standout Features

• AngularJS and Ionic Support - Optional AngularJS module provides ForerunnerDB as an angular service.
• Views - Virtual collections that are built from existing collections and limited by live queries.
• Joins - Query with joins across multiple collections and views.
• Sub-Queries - ForerunnerDB supports sub-queries across collections and views.
• Collection Groups - Add collections to a group and operate CRUD on them as a single entity.
• Data Binding (Browser Only) - Optional binding module to bind data to your DOM and have it update your page in realtime as data changes.
• Persistent Storage (Browser & Node.js) - Optional persist module to save your data and load it back at a later time, great for multi-page apps.
• Compression & Encryption - Support for compressing and encrypting your persisted data.
• Built-In REST Server (Node.js) - Optional REST server with powerful access control, remote procedures, access collections, views etc via REST interface. Rapid prototyping is made very easy with ForerunnerDB server-side.

What is ForerunnerDB

ForerunnerDB is a NoSQL JavaScript JSON database with a query language based on MongoDB (with some differences) and runs on browsers and Node.js. It is in use in many large production web applications and is transparently used by over 6 million clients. ForerunnerDB is the most advanced, battle-tested and production ready browser-based JSON database system available today.

What is ForerunnerDB's Primary Use Case?

ForerunnerDB was created primarily to allow web (and mobile web / hybrid) application developers to easily store, query and manipulate JSON data in the browser / mobile app via a simple query language, making handling JSON data significantly easier.

ForerunnerDB supports data persistence on both the client (via LocalForage) and in Node.js (by saving and loading JSON data files).

If you build advanced web applications with AngularJS or perhaps your own framework or if you are looking to build a server application / API that needs a fast queryable in-memory store with file-based data persistence and a very easy setup (simple installation via NPM and no requirements except Node.js) you will also find ForerunnerDB very useful.

An example hybrid application that runs on iOS, Android and Windows Mobile via Ionic (AngularJS + Cordova with some nice extensions) is available in this repository under the ionicExampleClient folder. See here for more details.

Download

NPM

If you are using Node.js (or have it installed) you can use NPM to download ForerunnerDB via:

npm install forerunnerdb

NPM Dev Builds

You can also install the development version which usually includes new features that are considered either unstable or untested. To install the development version you can ask NPM for the dev tag:

npm install forerunnerdb --tag dev

Bower

You can also install ForerunnerDB via the bower package manager:

bower install forerunnerdb

No Package Manager

If you are still a package manager hold-out or you would prefer a more traditional download, please click here.

How to Use

Use ForerunnerDB in Browser

fdb-all.min.js is the entire ForerunnerDB with all the added extras. If you prefer only the core database functionality (just collections, no views etc) you can use fdb-core.min.js instead. A list of the different builds is available for you to select the best build for your purposes.

Include the fdb-all.min.js file in your HTML (change path to the location you put forerunner):

<script src="./js/dist/fdb-all.min.js" type="text/javascript"></script>

Use ForerunnerDB in Node.js

After installing via npm (see above) you can require ForerunnerDB in your code:

var ForerunnerDB = require("forerunnerdb");
var fdb = new ForerunnerDB();

Create a Database

var db = fdb.db("myDatabaseName");

If you do not specify a database name a randomly generated one is provided instead.

Collections (Tables)

Data Binding: Enabled

To create or get a reference to a collection object, call db.collection (where collectionName is the name of your collection):

var collection = db.collection("collectionName");

In our examples we will use a collection called "item" which will store some fictitious items for sale:

var itemCollection = db.collection("item");

Auto-Creation

When you request a collection that does not yet exist it is automatically created. If it already exists you are given the reference to the existing collection. If you want ForerunnerDB to throw an error if a collection is requested that does not already exist you can pass an option to the collection() method instead:

var collection = db.collection("collectionName", {autoCreate: false});

Specifying a Primary Key Up-Front

If no primary key is specified ForerunnerDB uses "_id" by default.

On requesting a collection you can specify a primary key that the collection should be using. For instance to use a property called "name" as the primary key field:

var collection = db.collection("collectionName", {primaryKey: "name"});

You can also read or specify a primary key after instantiation via the primaryKey() method.

Capped Collections

Occasionally it is useful to create a collection that will store a finite number of records. When that number is reached, any further documents inserted into the collection will cause the oldest inserted document to be removed from the collection on a first-in-first-out rule (FIFO).

In this example we create a capped collection with a document limit of 5:

var collection = db.collection("collectionName", {capped: true, size: 5});

Inserting Documents

If you do not specify a value for the primary key, one will be automatically generated for any documents inserted into a collection. Auto-generated primary keys are pseudo-random 16 character strings.

PLEASE NOTE: When doing an insert into a collection, ForerunnerDB will automatically split the insert up into smaller chunks (usually of 100 documents) at a time to ensure the main processing thread remains unblocked. If you wish to be informed when the insert operation is complete you can pass a callback method to the insert call. Alternatively you can turn off this behaviour by calling yourCollection.deferredCalls(false);

You can either insert a single document object:

itemCollection.insert({
	_id: 3,
	price: 400,
	name: "Fish Bones"
});

or pass an array of documents:

itemCollection.insert([{
	_id: 4,
	price: 267,
	name:"Scooby Snacks"
}, {
	_id: 5,
	price: 234,
	name: "Chicken Yum Yum"
}]);

Inserting a Large Number of Documents

When inserting large amounts of documents ForerunnerDB may break your insert operation into multiple smaller operations (usually of 100 documents at a time) in order to avoid blocking the main processing thread of your browser / Node.js application. You can find out when an insert has completed either by passing a callback to the insert call or by switching off async behaviour.

Passing a callback:

itemCollection.insert([{
	_id: 4,
	price: 267,
	name:"Scooby Snacks"
}, {
	_id: 5,
	price: 234,
	name: "Chicken Yum Yum"
}], function (result) {
	// The result object will contain two arrays (inserted and failed)
	// which represent the documents that did get inserted and those
	// that didn't for some reason (usually index violation). Failed
	// items also contain a reason. Inspect the failed array for further
	// information.
});

If you wish to switch off async behaviour you can do so on a per-collection basis via:

db.collection('myCollectionName').deferredCalls(false);

After async behaviour (deferred calls) has been disabled, you can insert records and be sure that they will all have inserted before the next statement is processed by the application's main thread.

Inserting Special Objects

JSON has limitations on the types of objects it will serialise and de-serialise back to an object. Two very good examples of this are the Date() and RegExp() objects. Both can be serialised via JSON.stringify() but when calling JSON.parse() on the serialised version neither type will be "re-materialised" back to their object representations.

For example:

var a = {
	dt: new Date()
};

a.dt instanceof Date; // true

var b = JSON.stringify(a); // "{"dt":"2016-02-11T09:52:49.170Z"}"

var c = JSON.parse(b); // {dt: "2016-02-11T09:52:49.170Z"}

c.dt instanceof Date; // false

As you can see, parsing the JSON string works but the dt key no longer contains a Date instance and only holds the string representation of the date. This is a fundamental drawback of using JSON.stringify() and JSON.parse() in their native form.

If you want ForerunnerDB to serialise / de-serialise your object instances you must use this format instead:

var a = {
	dt: fdb.make(new Date())
};

By wrapping the new Date() in fdb.make() we allow ForerunnerDB to provide the Date() object with a custom .toJSON() method that serialises it differently to the native implementation.

For convenience the make() method is also available on all ForerunnerDB class instances e.g. db, collection, view etc. For instance you can access make via:

var fdb = new ForerunnerDB(),
	db = fdb.db('test'),
	coll = db.collection('testCollection'),
	date = new Date();

// All of these calls will do the same thing:
date = fdb.make(date);
date = db.make(date);
date = coll.make(date);

You can read more about how ForerunnerDB's serialiser works here.

Supported Instance Types and Usage

Date

var a = {
	dt: fdb.make(new Date())
};

RegExp

var a = {
	re: fdb.make(new RegExp(".*", "i"))
};

or

var a = {
	re: fdb.make(/.*/i))
};

Adding Custom Types to the Serialiser

ForerunnerDB's serialisation system allows for custom type handling so that you can expand JSON serialisation to your own custom class instances.

This can be a complex topic so it has been broken out into the Wiki section for further reading here.

Searching the Collection

PLEASE NOTE While we have tried to remain as close to MongoDB's query language as possible, small differences are present in the query matching logic. The main difference is described here: Find behaves differently from MongoDB

See the Special Considerations section for details about how names of keys / properties in a query object can affect a query's operation.

Much like MongoDB, searching for data in a collection is done using the find() method, which supports many of the same operators starting with a $ that MongoDB supports. For instance, finding documents in the collection where the price is greater than 90 but less than 150, would look like this:

itemCollection.find({
	price: {
		"$gt": 90,
		"$lt": 150
	}
});

And would return an array with all matching documents. If no documents match your search, an empty array is returned.

Regular Expressions

Searches support regular expressions for advanced text-based queries. Simply pass the regular expression object as the value for the key you wish to search, just like when using regular expressions with MongoDB.

Insert a document:

collection.insert([{
	"foo": "hello"
}]);

Search by regular expression:

collection.find({
	"foo": /el/
});

You can also use the RegExp object instead:

var myRegExp = new RegExp("el");

collection.find({
	"foo": myRegExp
});

Query Operators

ForerunnerDB supports many of the same query operators that MongoDB does, and adds some that are not available in MongoDB but which can help in browser-centric applications.

• $gt Greater Than
• $gte Greater Than / Equal To
• $lt Less Than
• $lte Less Than / Equal To
• $eq Equal To (==)
• $eeq Strict Equal To (===)
• $ne Not Equal To (!=)
• $nee Strict Not Equal To (!==)
• $not Apply boolean not to query
• $in Match Any Value In An Array Of Values
• $fastIn Match Any String or Number In An Array Of String or Numbers
• $nin Match Any Value Not In An Array Of Values
• $distinct Match By Distinct Key/Value Pairs
• $count Match By Length Of Sub-Document Array
• $or Match any of the conditions inside the sub-query
• $and Match all conditions inside the sub-query
• $exists Check that a key exists in the document
• $elemMatch Limit sub-array documents by query
• $elemsMatch Multiple document version of $elemMatch
• $aggregate Converts an array of documents into an array of values base on a path / key
• $near Geospatial operation finds outward from a central point

$gt

Selects those documents where the value of the field is greater than (i.e. >) the specified value.

{ field: {$gt: value} }

Usage

var fdb = new ForerunnerDB(),
	db = fdb.db("test"),
	coll = db.collection("test");
	
coll.insert([{
	_id: 1,
	val: 1
}, {
	_id: 2,
	val: 2
}, {
	_id: 3,
	val: 3
}]);

result = coll.find({
	val: {
		$gt: 1
	}
});

Result is:

[{
	_id: 2,
	val: 2
}, {
	_id: 3,
	val: 3
}]

$gte

Selects the documents where the value of the field is greater than or equal to (i.e. >=) the specified value.

{ field: {$gte: value} }

Usage

var fdb = new ForerunnerDB(),
	db = fdb.db("test"),
	coll = db.collection("test");
	
coll.insert([{
	_id: 1,
	val: 1
}, {
	_id: 2,
	val: 2
}, {
	_id: 3,
	val: 3
}]);

result = coll.find({
	val: {
		$gte: 1
	}
});

Result is:

[{
	_id: 1,
	val: 1
}, {
	_id: 2,
	val: 2
}, {
	_id: 3,
	val: 3
}]

$lt

Selects the documents where the value of the field is less than (i.e. <) the specified value.

{ field: { $lt: value} }

Usage

var fdb = new ForerunnerDB(),
	db = fdb.db("test"),
	coll = db.collection("test");
	
coll.insert([{
	_id: 1,
	val: 1
}, {
	_id: 2,
	val: 2
}, {
	_id: 3,
	val: 3
}]);

result = coll.find({
	val: {
		$lt: 2
	}
});

Result is:

[{
	_id: 1,
	val: 1
}]

$lte

Selects the documents where the value of the field is less than or equal to (i.e. <=) the specified value.

{ field: { $lte: value} }

Usage

var fdb = new ForerunnerDB(),
	db = fdb.db("test"),
	coll = db.collection("test");
	
coll.insert([{
	_id: 1,
	val: 1
}, {
	_id: 2,
	val: 2
}, {
	_id: 3,
	val: 3
}]);

result = coll.find({
	val: {
		$lte: 2
	}
});

Result is:

[{
	_id: 1,
	val: 1
}, {
	_id: 2,
	val: 2
}]
	```

#### $eq
Selects the documents where the value of the field is equal (i.e. ==) to the specified value.

```js
{field: {$eq: value} }

Usage

var fdb = new ForerunnerDB(),
	db = fdb.db("test"),
	coll = db.collection("test");
	
coll.insert([{
	_id: 1,
	val: 1
}, {
	_id: 2,
	val: 2
}, {
	_id: 3,
	val: 3
}]);

result = coll.find({
	val: {
		$eq: 2
	}
});

Result is:

[{
	_id: 2,
	val: 2
}]

$eeq

Selects the documents where the value of the field is strict equal (i.e. ===) to the specified value. This allows for strict equality checks for instance zero will not be seen as false because 0 !== false and comparing a string with a number of the same value will also return false e.g. ('2' == 2) is true but ('2' === 2) is false.

{field: {$eeq: value} }

Usage

var fdb = new ForerunnerDB(),
	db = fdb.db("test"),
	coll = db.collection("test");
	
coll.insert([{
	_id: 1,
	val: "2"
}, {
	_id: 2,
	val: 2
}, {
	_id: 3,
	val: "2"
}]);

result = coll.find({
	val: {
		$eeq: 2
	}
});

Result is:

[{
	_id: 2,
	val: 2
}]

$ne

Selects the documents where the value of the field is not equal (i.e. !=) to the specified value. This includes documents that do not contain the field.

{field: {$ne: value} }

Usage

var fdb = new ForerunnerDB(),
	db = fdb.db("test"),
	coll = db.collection("test");
	
coll.insert([{
	_id: 1,
	val: 1
}, {
	_id: 2,
	val: 2
}, {
	_id: 3,
	val: 3
}]);

result = coll.find({
	val: {
		$ne: 2
	}
});

Result is:

[{
	_id: 1,
	val: 1
}, {
	_id: 3,
	val: 3
}]

$nee

Selects the documents where the value of the field is not equal equal (i.e. !==) to the specified value. This allows for strict equality checks for instance zero will not be seen as false because 0 !== false and comparing a string with a number of the same value will also return false e.g. ('2' != 2) is false but ('2' !== 2) is true. This includes documents that do not contain the field.

{field: {$nee: value} }

Usage

var fdb = new ForerunnerDB(),
	db = fdb.db("test"),
	coll = db.collection("test");
	
coll.insert([{
	_id: 1,
	val: 1
}, {
	_id: 2,
	val: 2
}, {
	_id: 3,
	val: 3
}]);

result = coll.find({
	val: {
		$nee: 2
	}
});

Result is:

[{
	_id: 1,
	val: 1
}, {
	_id: 3,
	val: 3
}]

$not

Selects the documents where the result of the query inside the $not operator do not match the query object.

{$not: query}

Usage

var fdb = new ForerunnerDB(),
	db = fdb.db("test"),
	coll = db.collection("test");

coll.insert({
	_id: 1,
	name: 'John Doe',
	group: [{
		name: 'groupOne'
	}, {
		name: 'groupTwo'
	}]
});

coll.insert({
	_id: 2,
	name: 'Jane Doe',
	group: [{
		name: 'groupTwo'}
	]
});

result = coll.find({
	$not: {
		group: {
			name: 'groupOne'
		}
	}
});

Result is:

[{
 	_id: 2,
 	name: 'Jane Doe',
 	group: [{
 		name: 'groupTwo'}
 	]
}]

$in

If your field is a string or number and your array of values are also either strings or numbers you can utilise $fastIn which is an optimised $in query that uses indexOf() to identify matching values instead of looping over all items in the array of values and running a new matching process against each one. If your array of values include sub-queries or other complex logic you should use $in, not $fastIn.

Selects documents where the value of a field equals any value in the specified array.

{ field: { $in: [<value1>, <value2>, ... <valueN> ] } }

Usage

var fdb = new ForerunnerDB(),
	db = fdb.db("test"),
	coll = db.collection("test");
	
coll.insert([{
	_id: 1,
	val: 1
}, {
	_id: 2,
	val: 2
}, {
	_id: 3,
	val: 3
}]);

result = coll.find({
	val: {
		$in: [1, 3]
	}
});

Result is:

[{
	_id: 1,
	val: 1
}, {
	_id: 3,
	val: 3
}]

$fastIn

You can use $fastIn instead of $in when your field contains a string or number and your array of values contains only strings or numbers. $fastIn utilises indexOf() to speed up performance of the query. This means that the array of values is not evaluated for sub-queries, other operators like $gt etc, and it is assumed that the array of values is a completely flat array, filled only with strings or numbers.

Selects documents where the string or number value of a field equals any string or number value in the specified array.

The array of values MUST be a flat array and contain only strings or numbers.

{ field: { $fastIn: [<value1>, <value2>, ... <valueN> ] } }

Usage

var fdb = new ForerunnerDB(),
	db = fdb.db("test"),
	coll = db.collection("test");
	
coll.insert([{
	_id: 1,
	val: 1
}, {
	_id: 2,
	val: 2
}, {
	_id: 3,
	val: 3
}]);

result = coll.find({
	val: {
		$fastIn: [1, 3]
	}
});

Result is:

[{
	_id: 1,
	val: 1
}, {
	_id: 3,
	val: 3
}]

$nin

Selects documents where the value of a field does not equal any value in the specified array.

{ field: { $nin: [ <value1>, <value2> ... <valueN> ]} }

Usage

var fdb = new ForerunnerDB(),
	db = fdb.db("test"),
	coll = db.collection("test");
	
coll.insert([{
	_id: 1,
	val: 1
}, {
	_id: 2,
	val: 2
}, {
	_id: 3,
	val: 3
}]);

result = coll.find({
	val: {
		$nin: [1, 3]
	}
});

Result is:

[{
	_id: 2,
	val: 2
}]

$distinct

Selects the first document matching a value of the specified field. If any further documents have the same value for the specified field they will not be returned.

{ $distinct: { field: 1 } }

Usage

var fdb = new ForerunnerDB(),
	db = fdb.db("test"),
	coll = db.collection("test");
	
coll.insert([{
	_id: 1,
	val: 1
}, {
	_id: 2,
	val: 1
}, {
	_id: 3,
	val: 1
}, {
	_id: 4,
	val: 2
}]);

result = coll.find({
	$distinct: {
		val: 1
	}
});

Result is:

[{
	_id: 1,
	val: 1
}, {
	_id: 4,
	val: 2
}]

$count

Version >= 1.3.326

This is equivalent to MongoDB's $size operator but please see below for usage.

Selects documents based on the length (count) of items in an array inside a document.

{ $count: { field: <value> } }

Select Documents Where The "arr" Array Field Has Only 1 Item

var fdb = new ForerunnerDB(),
	db = fdb.db("test"),
	coll = db.collection("test");
	
coll.insert([{
	_id: 1,
	arr: []
}, {
	_id: 2,
	arr: [{
		val: 1		
	}]
}, {
	_id: 3,
	arr: [{
		val: 1
	}, {
		val: 2		
	}]
}]);

result = coll.find({
	$count: {
		arr: 1
	}
});

Result is:

[{
	_id: 2,
	arr: [{
		val: 1		
	}]
}]

Select Documents Where The "arr" Array Field Has More Than 1 Item

var fdb = new ForerunnerDB(),
	db = fdb.db("test"),
	coll = db.collection("test");
	
coll.insert([{
	_id: 1,
	arr: []
}, {
	_id: 2,
	arr: [{
		val: 1		
	}]
}, {
	_id: 3,
	arr: [{
		val: 1
	}, {
		val: 2		
	}]
}]);

result = coll.find({
	$count: {
		arr: {
			$gt: 1
		}
	}
});

Result is:

[{
	_id: 3,
	arr: [{
		val: 1
	}, {
		val: 2		
	}]
}]

$or

The $or operator performs a logical OR operation on an array of two or more and selects the documents that satisfy at least one of the .

{ $or: [ { <expression1> }, { <expression2> }, ... , { <expressionN> } ] }

Usage

var fdb = new ForerunnerDB(),
	db = fdb.db("test"),
	coll = db.collection("test");
	
coll.insert([{
	_id: 1,
	val: 1
}, {
	_id: 2,
	val: 2
}, {
	_id: 3,
	val: 3
}]);

result = coll.find({
	$or: [{
		val: 1
	}, {
		val: {
			$gte: 3 
		}
	}]
});

Result is:

[{
	_id: 1,
	val: 1
}, {
	_id: 3,
	val: 3
}]

$and

Performs a logical AND operation on an array of two or more expressions (e.g. , , etc.) and selects the documents that satisfy all the expressions in the array. The $and operator uses short-circuit evaluation. If the first expression (e.g. ) evaluates to false, ForerunnerDB will not evaluate the remaining expressions.

{ $and: [ { <expression1> }, { <expression2> } , ... , { <expressionN> } ] }

Usage

var fdb = new ForerunnerDB(),
	db = fdb.db("test"),
	coll = db.collection("test");
	
coll.insert([{
	_id: 1,
	val: 1
}, {
	_id: 2,
	val: 2
}, {
	_id: 3,
	val: 3
}]);

result = coll.find({
	$and: [{
		_id: 3
	}, {
		val: {
			$gte: 3 
		}
	}]
});

Result is:

[{
	_id: 3,
	val: 3
}]

$exists

When is true, $exists matches the documents that contain the field, including documents where the field value is null. If is false, the query returns only the documents that do not contain the field.

{ field: { $exists: <boolean> } }

Usage

var fdb = new ForerunnerDB(),
	db = fdb.db("test"),
	coll = db.collection("test");
	
coll.insert([{
	_id: 1,
	val: 1
}, {
	_id: 2,
	val: 2,
	moo: "hello"
}, {
	_id: 3,
	val: 3
}]);

result = coll.find({
	moo: {
		$exists: true
	}
});

Result is:

[{
	_id: 2,
	val: 2,
	moo: "hello"
}]

Projection

$elemMatch

The $elemMatch operator limits the contents of an array field from the query results to contain only the first element matching the $elemMatch condition.

The $elemMatch operator is specified in the options object of the find call rather than the query object.

MongoDB $elemMatch Documentation

Usage

var fdb = new ForerunnerDB(),
	db = fdb.db("test"),
	coll = db.collection("test");
	
coll.insert({
	names: [{
		_id: 1,
		text: "Jim"
	}, {
		_id: 2,
		text: "Bob"
	}, {
		_id: 3,
		text: "Bob"
	}, {
		_id: 4,
		text: "Anne"
	}, {
		_id: 5,
		text: "Simon"
	}, {
		_id: 6,
		text: "Uber"
	}]
});

result = coll.find({}, {
	$elemMatch: {
		names: {
			text: "Bob"
		}
	}
});

Result is:

{
	names: [{
		_id: 2,
		text: "Bob"
	}]
}

Notice that only the FIRST item matching the $elemMatch clause is returned in the names array. If you require multiple matches use the ForerunnerDB-specific $elemsMatch operator instead.

$elemsMatch

The $elemsMatch operator limits the contents of an array field from the query results to contain only the elements matching the $elemMatch condition.

The $elemsMatch operator is specified in the options object of the find call rather than the query object.

Usage

var fdb = new ForerunnerDB(),
	db = fdb.db("test"),
	coll = db.collection("test");
	
coll.insert({
	names: [{
		_id: 1,
		text: "Jim"
	}, {
		_id: 2,
		text: "Bob"
	}, {
		_id: 3,
		text: "Bob"
	}, {
		_id: 4,
		text: "Anne"
	}, {
		_id: 5,
		text: "Simon"
	}, {
		_id: 6,
		text: "Uber"
	}]
});

result = coll.find({}, {
	$elemsMatch: {
		names: {
			text: "Bob"
		}
	}
});

Result is:

{
	names: [{
		_id: 2,
		text: "Bob"
	}, {
		_id: 3,
		text: "Bob"
	}]
}

Notice that all items matching the $elemsMatch clause are returned in the names array. If you require match on ONLY the first item use the MongoDB-compliant $elemMatch operator instead.

$aggregate

Coverts an array of documents into an array of values that are derived from a key or path in the documents. This is very useful when combined with the $find operator to run sub-queries and return arrays of values from the results.

{ $aggregate: path}

Usage

var fdb = new ForerunnerDB(),
	db = fdb.db("test"),
	coll = db.collection("test");
	
coll.insert([{
	_id: 1,
	val: 1
}, {
	_id: 2,
	val: 2
}, {
	_id: 3,
	val: 3
}]);

result = coll.find({}, {
	$aggregate: "val"
});

Result is:

[1, 2, 3]

$near

PLEASE NOTE: BETA STATUS - PASSES UNIT TESTING BUT MAY BE UNSTABLE

Finds other documents whose co-ordinates based on a 2d index are within the specified distance from the specified centre point. Co-ordinates must be presented in latitude / longitude for $near to work.

{
	field: {
		$near: {
			$point: [<latitude number>, <longitude number>],
			$maxDistance: <number>,
			$distanceUnits: <units string>
		}
	}
}

Usage

var fdb = new ForerunnerDB(),
	db = fdb.db("test"),
	coll = db.collection("test");

coll.insert([{
	latLng: [51.50722, -0.12750],
	name: 'Central London'
}, {
	latLng: [51.525745, -0.167550], // 2.18 miles
	name: 'Marylebone, London'
}, {
	latLng: [51.576981, -0.335091], // 10.54 miles
	name: 'Harrow, London'
}, {
	latLng: [51.769451, 0.086509], // 20.33 miles
	name: 'Harlow, Essex'
}]);

// Create a 2d index on the lngLat field
coll.ensureIndex({
	latLng: 1
}, {
	type: '2d'
});

// Query index by distance
// $near queries are sorted by distance from centre point by default
result = coll.find({
	latLng: {
		$near: {
			$point: [51.50722, -0.12750],
			$maxDistance: 3,
			$distanceUnits: 'miles'
		}
	}
});

Result is:

[{
	"lngLat": [51.50722, -0.1275],
	"name": "Central London",
	"_id": "1f56c0b5885de40"
}, {
	"lngLat": [51.525745, -0.16755],
	"name": "Marylebone, London",
	"_id": "372a34d9f17fbe0"
}]

Ordering / Sorting Results

You can specify an $orderBy option along with the find call to order/sort your results. This uses the same syntax as MongoDB:

itemCollection.find({
	price: {
		"$gt": 90,
		"$lt": 150
	}
}, {
	$orderBy: {
		price: 1 // Sort ascending or -1 for descending
	}
});

Grouping Results

Version >= 1.3.757

You can specify a $groupBy option along with the find call to group your results:

myColl = db.collection('myColl');

myColl.insert([{
	"price": "100",
	"category": "dogFood"
}, {
 	"price": "60",
 	"category": "catFood"
}, {
	"price": "70",
	"category": "catFood"
}, {
	"price": "65",
	"category": "catFood"
}, {
	"price": "35",
	"category": "dogFood"
}]);

myColl.find({}, {
	$groupBy: {
		"category": 1 // Group using the "category" field. Path's are also allowed e.g. "category.name"
	}
});

Result is:

{
	"dogFood": [{
		"price": "100",
		"category": "dogFood"
	}, {
		"price": "35",
		"category": "dogFood"
	}],
	"catFood": [{
		"price": "60",
		"category": "catFood"
	}, {
		"price": "70",
		"category": "catFood"
	}, {
		"price": "65",
		"category": "catFood"
	}],
}

Limiting Return Fields - Querying for Partial Documents / Objects

You can specify which fields are included in the return data for a query by adding them in the options object. This returns a partial document for each matching document in your query.

This follows the same rules specified by MongoDB here:

MongoDB Documentation

Please note that the primary key field will always be returned unless explicitly excluded from the results via "_id: 0".

Usage

var fdb = new ForerunnerDB(),
	db = fdb.db("test"),
	coll = db.collection("test");

coll.insert([{
	_id: 1,
	text: "Jim",
	val: 2131232,
	arr: [
		"foo",
		"bar",
		"you"
	]
}]);

Now query for only the "text" field of each document:

result = coll.find({}, {
	text: 1
});

Result is:

[{
	_id: 1,
	text: "Jim"
}]

Notice the _id field is ALWAYS included in the results unless you explicitly exclude it:

result = coll.find({}, {
	_id: 0,
	text: 1
});

Result is:

[{
	text: "Jim"
}]

Pagination / Paging Through Results

Version >= 1.3.55

It is often useful to limit the number of results and then page through the results one page at a time. ForerunnerDB supports an easy pagination system via the $page and $limit query options combination.

Usage

var fdb = new ForerunnerDB(),
	db = fdb.db("test"),
	coll = db.collection("test"),
	data = [],
	count = 100,
	result,
	i;

// Generate random data
for (i = 0; i < count; i++) {
	data.push({
		_id: String(i),
		val: i
	});
}

coll.insert(data);

// Query the first 10 records (page indexes are zero-based
// so the first page is page 0 not page 1)
result = coll.find({}, {
	$page: 0,
	$limit: 10
});

// Query the next 10 records
result = coll.find({}, {
	$page: 1,
	$limit: 10
});

Skipping Records in a Query

Version >= 1.3.55

You can skip records at the beginning of a query result by providing the $skip query option. This operates in a similar fashion to the MongoDB skip() method.

Usage

var fdb = new ForerunnerDB(),
	db = fdb.db("test"),
	coll = db.collection("test").truncate(),
	data = [],
	count = 100,
	result,
	i;

// Generate random data
for (i = 0; i < count; i++) {
	data.push({
		_id: String(i),
		val: i
	});
}

coll.insert(data);
result = coll.find({}, {
	$skip: 50
});

Finding and Returning Sub-Documents

When you have documents that contain arrays of sub-documents it can be useful to search and extract them. Consider this data structure:

var fdb = new ForerunnerDB(),
	db = fdb.db("test"),
	coll = db.collection("test").truncate(),
	result,
	i;

coll.insert({
	_id: "1",
	arr: [{
		_id: "332",
		val: 20,
		on: true
	}, {
		_id: "337",
		val: 15,
		on: false
	}]
});

/**
 * Finds sub-documents from the collection's documents.
 * @param {Object} match The query object to use when matching parent documents
 * from which the sub-documents are queried.
 * @param {String} path The path string used to identify the key in which
 * sub-documents are stored in parent documents.
 * @param {Object=} subDocQuery The query to use when matching which sub-documents
 * to return.
 * @param {Object=} subDocOptions The options object to use when querying for
 * sub-documents.
 * @returns {*}
 */
result = coll.findSub({
	_id: "1"
}, "arr", {
	on: false
}, {
	//$stats: true,
	//$split: true
});

The result of this query is an array containing the sub-documents that matched the query parameters:

[{
	_id: "337",
	val: 15,
	on: false
}]

The result of findSub never returns a parent document's data, only data from the matching sub-document(s)

The fourth parameter (options object) allows you to specify if you wish to have stats and if you wish to split your results into separate arrays for each matching parent document.

Subqueries and Subquery Syntax

Version >= 1.3.469

Subqueries are ForerunnerDB specific and do not work in MongoDB

A subquery is a query object within another query object.

Subqueries are useful when the query you wish to run is reliant on data inside another collection or view and you do not want to run a separate query first to retrieve that data.

Subqueries in ForerunnerDB are specified using the $find operator inside your query.

Take the following example data:

var fdb = new ForerunnerDB(),
	db = fdb.db("test"),
	users = db.collection("users"),
	admins = db.collection("admins");
	
users.insert([{
	_id: 1,
	name: "Jim"
}, {
	_id: 2,
	name: "Bob"
}, {
	_id: 3,
	name: "Bob"
}, {
	_id: 4,
	name: "Anne"
}, {
	_id: 5,
	name: "Simon"
}]);

admins.insert([{
	_id: 2,
	enabled: true
}, {
	_id: 4,
	enabled: true
}, {
	_id: 5,
	enabled: false
}]);

result = users.find({
	_id: {
		$in: {
			$find: {
				$from: "admins",
				$query: {
					enabled: true
				},
				$options: {
					$aggregate: "_id"
				}
			}
		}
	}
});

When this query is executed the $find sub-query object is replaced with the results from the sub-query so that the final query with (aggregated)#$aggregate _id field looks like this:

result = users.find({
	_id: {
		$in: [3, 4]
	}
});

The result of the query after execution is:

[{
	"_id": 3,
	"name": "Bob"
}, {
	"_id": 4,
	"name": "Anne"
}]

Updating the Collection

This is one of the areas where ForerunnerDB and MongoDB are different. By default ForerunnerDB updates only the keys you specify in your update document, rather than outright replacing the matching documents like MongoDB does. In this sense ForerunnerDB behaves more like MySQL. In the call below, the update will find all documents where the price is greater than 90 and less than 150 and then update the documents' key "moo" with the value true.

collection.update({
	price: {
		"$gt": 90,
		"$lt": 150
	}
}, {
	moo: true
});

If you wish to fully replace a document with another one you can do so using the $replace operator described in the Update Operators section below.

If you want to replace a key's value you can use the $overwrite operator described in the Update Operators section below.

Quick Updates

You can target individual documents for update by their id (primary key) via a quick helper method:

collection.updateById(1, {price: 180});

This will update the document with the _id field of 1 to a new price of 180.

Update Operators

• $addToSet
• $cast
• $each
• $inc
• $move
• $mul
• $overwrite
• $push
• $pull
• $pullAll
• $pop
• $rename
• $replace
• $splicePush
• $splicePull
• $toggle
• $unset
• Array Positional in Updates (.$)

$addToSet

Adds an item into an array only if the item does not already exist in the array.

ForerunnerDB supports the $addToSet operator as detailed in the MongoDB documentation. Unlike MongoDB, ForerunnerDB also allows you to specify a matching field / path to check uniqueness against by using the $key property.

In the following example $addToSet is used to check uniqueness against the whole document being added:

// Create a collection document
db.collection("test").insert({
	_id: "1",
	arr: []
});

// Update the document by adding an object to the "arr" array
db.collection("test").update({
	_id: "1"
}, {
	$addToSet: {
		arr: {
			name: "Fufu",
			test: "1"
		}
	}
});

// Try and do it again... this will fail because a
// matching item already exists in the array
db.collection("test").update({
	_id: "1"
}, {
	$addToSet: {
		arr: {
			name: "Fufu",
			test: "1"
		}
	}
});

Now in the example below we specify which key to test uniqueness against:

// Create a collection document
db.collection("test").insert({
	_id: "1",
	arr: []
});

// Update the document by adding an object to the "arr" array
db.collection("test").update({
	_id: "1"
}, {
	$addToSet: {
		arr: {
			name: "Fufu",
			test: "1"
		}
	}
});

// Try and do it again... this will work because the
// key "test" is different for the existing and new objects
db.collection("test").update({
	_id: "1"
}, {
	$addToSet: {
		arr: {
			$key: "test",
			name: "Fufu",
			test: "2"
		}
	}
});

You can also specify the key to check uniqueness against as an object path such as 'moo.foo'.

$cast

Version >= 1.3.34

The $cast operator allows you to change a property's type within a document. If used to cast a property to an array or object the property is set to a new blank array or object respectively.

This example changes the type of the "val" property from a string to a number:

db.collection("test").insert({
	val: "1.2"
});

db.collection("test").update({}, {
	$cast: {
		val: "number"
	}
});

JSON.stringify(db.collection("test").find());

Result:

[{
	"_id": "1d6fbf16e080de0",
	"val": 1.2
}]

You can also use cast to ensure that an array or object exists on a property without overwriting that property if one already exists:

db.collection("test").insert({
	_id: "moo",
	arr: [{
		test: true
	}]
});

db.collection("test").update({
	_id: "moo"
}, {
	$cast: {
		arr: "array"
	}
});

JSON.stringify(db.collection("test").find());

Result:

[{
	"_id": "moo",
	"arr": [{
		"test": true
	}]
}]

Should you wish to initialise an array or object with specific data if the property is not currently of that type rather than initialising as a blank array / object, you can specify the data to use by including a $data property in your $cast operator object:

db.collection("test").insert({
	_id: "moo"
});

db.collection("test").update({
	_id: "moo"
}, {
	$cast: {
		orders: "array",
		$data: [{
			initial: true
		}]
	}
});

JSON.stringify(db.collection("test").find());

Result:

[{
	"_id": "moo",
	"orders":[{
		"initial": true
	}]
}]

$each

Version >= 1.3.34

$each allows you to iterate through multiple update operations on the same query result. Use $each when you wish to execute update operations in sequence or on the same query. Using $each is slightly more performant than running each update operation one after the other calling update().

Consider the following sequence of update calls that define a couple of nested arrays and then push a value to the inner-nested array:

db.collection("test").insert({
	_id: "445324",
	count: 5
});

db.collection("test").update({
	_id: "445324"
}, {
	$cast: {
		arr: "array",
		$data: [{}]
	}
});

db.collection("test").update({
	_id: "445324"
}, {
	arr: {
		$cast: {
			secondArr: "array"
		}
	}
});

db.collection("test").update({
	_id: "445324"
}, {
	arr: {
		$push: {
			secondArr: "moo"
		}
	}
});

JSON.stringify(db.collection("test").find());

Result:

[
	{
		"_id": "445324",
		"count": 5,
		"arr": [{"secondArr": ["moo"]}]
	}
]

These calls a wasteful because each update() call must query the collection for matching documents before running the update against them. With $each you can pass a sequence of update operations and they will be executed in order:

db.collection("test").insert({
	_id: "445324",
	count: 5
});

db.collection("test").update({
	_id: "445324"
}, {
	$each: [{
		$cast: {
			arr: "array",
			$data: [{}]
		}
	}, {
		arr: {
			$cast: {
				secondArr: "array"
			}
		}
	}, {
		arr: {
			$push: {
				secondArr: "moo"
			}
		}
	}]
});

JSON.stringify(db.collection("test").find());

Result:

[
	{
		"_id": "445324",
		"count": 5,
		"arr": [{"secondArr": ["moo"]}]
	}
]

As you can see the single sequenced call produces the same output as the multiple update() calls but will run slightly faster and use fewer resources.

$inc

The $inc operator increments / decrements a field value by the given number.

db.collection("test").update({
	<query>
}, {
	$inc: {
		<field>: <value>
	}
});

In the following example, the "count" field is decremented by 1 in the document that matches the id "445324":

db.collection("test").insert({
	_id: "445324",
	count: 5
});

db.collection("test").update({
	_id: "445324"
}, {
	$inc: {
		count: -1
	}
});

JSON.stringify(db.collection("test").find());

Result:

[{
	"_id": "445324",
	"count": 4
}]

Using a positive number will increment, using a negative number will decrement.

$move

The $move operator moves an item that exists inside a document's array from one index to another.

db.collection("test").update({
	<query>
}, {
	$move: {
		<arrayField>: <value|query>,
		$index: <index>
	}
});

The following example moves "Milk" in the "shoppingList" array to index 1 in the document with the id "23231":

db.users.update({
	_id: "23231"
}, {
	$move: {
		shoppingList: "Milk"
		$index: 1
	}
});

$mul

The $mul operator multiplies a field value by the given number and sets the result as the field's new value.

db.collection("test").update({
	<query>
}, {
	$mul: {
		<field>: <value>
	}
});

In the following example, the "value" field is multiplied by 2 in the document that matches the id "445324":

db.collection("test").insert({
	_id: "445324",
	value: 5
});

db.collection("test").update({
	_id: "445324"
}, {
	$mul: {
		value: 2
	}
});

JSON.stringify(db.collection("test").find());

Result:

[{
	"_id": "445324",
	"value": 10
}]

$overwrite

The $overwrite operator replaces a key's value with the one passed, overwriting it completely. This operates the same way that MongoDB's default update behaviour works without using the $set operator.

If you wish to fully replace a document with another one you can do so using the $replace operator instead.

The $overwrite operator is most useful when updating an array field to a new type such as an object. By default ForerunnerDB will detect an array and step into the array objects one at a time and apply the update to each object. When you use $overwrite you can replace the array instead of stepping into it.

db.collection("test").update({
	<query>
}, {
	$overwrite: {
		<field>: <value>,
		<field>: <value>,
		<field>: <value>
	}
});

In the following example the "arr" field (initially an array) is replaced by an object:

db.collection("test").insert({
	_id: "445324",
	arr: [{
		foo: 1
	}]
});

db.collection("test").update({
	_id: "445324"
}, {
	$overwrite: {
		arr: {
			moo: 1
		}
	}
});

JSON.stringify(db.collection("test").find());

Result:

[{
	"_id": "445324",
	"arr": {
		"moo": 1
	}
}]

$push

The $push operator appends a specified value to an array.

db.collection("test").update({
	<query>
}, {
	$push: {
		<field>: <value>
	}
});

The following example appends "Milk" to the "shoppingList" array in the document with the id "23231":

db.collection("test").insert({
	_id: "23231",
	shoppingList: []
});

db.collection("test").update({
	_id: "23231"
}, {
	$push: {
		shoppingList: "Milk"
	}
});

JSON.stringify(db.collection("test").find());

Result:

[{
	"_id": "23231",
	"shoppingList": [
		"Milk"
	]
}]

$pull

The $pull operator removes a specified value or values that match an input query.

db.collection("test").update({
	<query>
}, {
	$pull: {
		<arrayField>: <value|query>
	}
});

The following example removes the "Milk" entry from the "shoppingList" array:

db.users.update({
	_id: "23231"
}, {
	$pull: {
		shoppingList: "Milk"
	}
});

If an array element is an embedded document (JavaScript object), the $pull operator applies its specified query to the element as though it were a top-level object.

$pullAll

The $pullAll operator removes all values / array entries that match an input query from the target array field.

db.collection("test").update({
	<query>
}, {
	$pullAll: {
		<arrayField>: <value|query>
	}
});

The following example removes all instances of "Milk" and "Toast from the "items" array:

db.users.update({
	_id: "23231"
}, {
	$pullAll: {
		items: ["Milk", "Toast"]
	}
});

If an array element is an embedded document (JavaScript object), the $pullAll operator applies its specified query to the element as though it were a top-level object.

$pop

The $pop operator removes an element from an array at the beginning or end. If you wish to remove an element from the end of the array pass 1 in your value. If you wish to remove an element from the beginning of an array pass -1 in your value.

db.collection("test").update({
	<query>
}, {
	$pop: {
		<field>: <value>
	}
});

The following example pops the item from the beginning of the "shoppingList" array:

db.collection("test").insert({
	_id: "23231",
	shoppingList: [{
		_id: 1,
		name: "One"
	}, {
		_id: 2,
		name: "Two"
	}, {
		_id: 3,
		name: "Three"
	}]
});

db.collection("test").update({
	_id: "23231"
}, {
	$pop: {
		shoppingList: -1 // -1 pops from the beginning, 1 pops from the end
	}
});

JSON.stringify(db.collection("test").find());

Result:

[{
	_id: "23231",
	shoppingList: [{
		_id: 2,
		name: "Two"
	}, {
		_id: 3,
		name: "Three"
	}]
}]

$rename

Renames a field in any documents that match the query with a new name.

db.collection("test").update({
	<query>
}, {
	$rename: {
		<field>: <newName>
	}
});

The following example renames the "action" field to "jelly":

db.collection("test").insert({
	_id: "23231",
	action: "Foo"
});

db.collection("test").update({
	_id: "23231"
}, {
	$rename: {
		action: "jelly"
	}
});

JSON.stringify(db.collection("test").find());

Result:

[{
 	_id: "23231",
 	jelly: "Foo"
 }]

$replace

PLEASE NOTE: $replace can only be used on the top-level. Nested $replace operators are not currently supported and may cause unexpected behaviour.

The $replace operator will take the passed object and overwrite the target document with the object's keys and values. If a key exists in the existing document but not in the passed object, ForerunnerDB will remove the key from the document.

The $replace operator is equivalent to calling MongoDB's update without using a MongoDB $set operator.

When using $replace the primary key field will NEVER be replaced even if it is specified. If you wish to change a record's primary key id, remove the document and insert a new one with your desired id.

db.collection("test").update({
	<query>
}, {
	$replace: {
		<field>: <value>,
		<field>: <value>,
		<field>: <value>
	}
});

In the following example the existing document is outright replaced by a new one:

db.collection("test").insert({
	_id: "445324",
	name: "Jill",
	age: 15
});

db.collection("test").update({
	_id: "445324"
}, {
	$replace: {
		job: "Frog Catcher"
	}
});

JSON.stringify(db.collection("test").find());

Result:

[{
	"_id": "445324",
	"job": "Frog Catcher"
}]

$splicePush

The $splicePush operator adds an item into an array at a specified index.

db.collection("test").update({
	<query>
}, {
	$splicePush: {
		<field>: <value>
		$index: <index>
	}
});

The following example inserts "Milk" to the "shoppingList" array at index 1 in the document with the id "23231":

db.collection("test").insert({
	_id: "23231",
	shoppingList: [
		"Sugar",
		"Tea",
		"Coffee"
	]
});

db.collection("test").update({
	_id: "23231"
}, {
	$splicePush: {
		shoppingList: "Milk",
		$index: 1
	}
});

JSON.stringify(db.collection("test").find());

Result:

[
	{
		"_id": "23231",
		"shoppingList": [
			"Sugar",
			"Milk",
			"Tea",
			"Coffee"
		]
	}
]

$splicePull

The $splicePull operator removes an item (or items) from an array at a specified index. If you specify a $count operator the splicePull operation will remove from the $index to the number of items you specify. $count defaults to 1 if it is not specified.

db.collection("test").update({
	<query>
}, {
	$splicePull: {
		<field>: {
			$index: <index>,
			$count: <integer>
		}
	}
});

The following example inserts "Milk" to the "shoppingList" array at index 1 in the document with the id "23231":

db.collection("test").insert({
	_id: "23231",
	shoppingList: [
		"Sugar",
		"Tea",
		"Coffee"
	]
});

db.collection("test").update({
	_id: "23231"
}, {
	$splicePull: {
		shoppingList: {
			$index: 1
		}
	}
});

JSON.stringify(db.collection("test").find());

Result:

[
	{
		"_id": "23231",
		"shoppingList": [
			"Sugar",
			"Milk",
			"Tea",
			"Coffee"
		]
	}
]

$toggle

The $toggle operator inverts the value of a field with a boolean. If the value is true before toggling, after toggling it will be false and vice versa.

db.collection("test").update({
	<query>
}, {
	$toggle: {
		<field>: 1
	}
});

In the following example, the "running" field is toggled from true to false:

db.collection("test").insert({
	_id: "445324",
	running: true
});

db.collection("test").update({
	_id: "445324"
}, {
	$toggle: {
		running: 1
	}
});

JSON.stringify(db.collection("test").find());

Result:

[{
	"_id": "445324",
	"running": false
}]

$unset

The $unset operator removes a field from a document.

db.collection("test").update({
	<query>
}, {
	$unset: {
		<field>: 1
	}
});

In the following example, the "count" field is remove from the document that matches the id "445324":

db.collection("test").insert({
	_id: "445324",
	count: 5
});

db.collection("test").update({
	_id: "445324"
}, {
	$unset: {
		count: 1
	}
});

JSON.stringify(db.collection("test").find());

Result:

[{
	"_id": "445324"
}]

Array Positional in Updates (.$)

Often you want to update a sub-document stored inside an array. You can use the array positional operator to tell ForerunnerDB that you wish to update a sub-document that matches your query clause.

The following example updates the sub-document in the array "arr" with the _id "foo" so that the "name" property is set to "John":

db.collection("test").insert({
	_id: "2",
	arr: [{
		_id: "foo",
		name: "Jim"
	}]
});

var result = db.collection("test").update({
	_id: "2",
	"arr": {
		"_id": "foo"
	}
}, {
	"arr.$": {
		name: "John"
	}
});

Internally this operation checks the update for property's ending in ".$" and then looks at the query part of the call to see if a corresponding clause exists for it. In the example above the "arr.$" property in the update part has a corresponding "arr" in the query part which determines which sub-documents are to be updated based on if they match or not.

Upsert Documents

Upserts are operations that automatically decide if the database should run an insert or an update operation based on the data you provide.

Using upsert() is effectively the same as using insert(). You pass an object or array of objects to the upsert() method and they are processed.

// This will execute an insert operation because a document with the _id "1" does not
// currently exist in the database.
db.collection("test").upsert({
	"_id": "1",
	"test": true
});

db.collection("test").find(); // [{"_id": "1", "test": true}]

// We now perform an upsert and change "test" to false. This will perform an update operation
// since a document with the _id "1" now exists.
db.collection("test").upsert({
	"_id": "1",
	"test": false
});

db.collection("test").find(); // [{"_id": "1", "test": false}]

One of the restrictions of upsert() is that you cannot use any update operators in your document because the operation could be an insert. For this reason, upserts should only contain data and no $ operators like $push, $unset etc.

An upsert operation both returns an array of results and accepts a callback that will receive the same array data on what operations were done for each document passed, as well as the result of that operation. See the http://forerunnerdb.com/source/doc/Collection.html#upsert(upsert documentation) for more details.

Count Documents

The count() method is useful when you want to get a count of the number of documents in a collection or a count of documents that match a specified query.

Count All Documents

// Cound all documents in the "test" collection
var num = db.collection("test").count();

Count Documents Based on Query

// Get all documents whos myField property has the value of 1
var num = db.collection("test").count({
	myField: 1
});

Get Data Item By Reference

JavaScript objects are passed around as references to the same object. By default when you query ForerunnerDB it will "decouple" the results from the internal objects stored in the collection. If you would prefer to get the reference instead of decoupled object you can specify this in the query options like so:

var result = db.collection("item").find({}, {
	$decouple: false
});

If you do not specify a decouple option, ForerunnerDB will default to true and return decoupled objects.

Keep in mind that if you switch off decoupling for a query and then modify any object returned, it will also modify the internal object held in ForerunnerDB, which could result in incorrect index data as well as other anomalies.

Primary Keys

If your data uses different primary key fields from the default "_id" then you need to tell the collection. Simply call the primaryKey() method with the name of the field your primary key is stored in:

collection.primaryKey("itemId");

When you change the primary key field name, methods like updateById will use this field automatically instead of the default one "_id".

Removing Documents

Removing is as simple as doing a normal find() call, but with the search for docs you want to remove. Remove all documents where the price is greater than or equal to 100:

collection.remove({
	price: {
		"$gte": 100
	}
});

Joins

Sometimes you want to join two or more collections when running a query and return a single document with all the data you need from those multiple collections. ForerunnerDB supports collection joins via a simple options key "$join". For instance, let's setup a second collection called "purchase" in which we will store some details about users who have ordered items from the "item" collection we initialised above:

var fdb = new ForerunnerDB(),
	db = fdb.db("test"),
	itemCollection = db.collection("item"),
	purchaseCollection = db.collection("purchase");

itemCollection.insert([{
	_id: 1,
	name: "Cat Litter",
	price: 200
}, {
	_id: 2,
	name: "Dog Food",
	price: 100
}, {
	_id: 3,
	price: 400,
	name: "Fish Bones"
}, {
	_id: 4,
	price: 267,
	name:"Scooby Snacks"
}, {
	_id: 5,
	price: 234,
	name: "Chicken Yum Yum"
}]);

purchaseCollection.insert([{
	itemId: 4,
	user: "Fred Bloggs",
	quantity: 2
}, {
	itemId: 4,
	user: "Jim Jones",
	quantity: 1
}]);

Now, when we find data from the "item" collection we can grab all the users that ordered that item as well and store them in a key called "purchasedBy":

itemCollection.find({}, {
	"$join": [{
		"purchase": {
			"itemId": "_id",
			"$as": "purchasedBy",
			"$require": false,
			"$multi": true
		}
	}]
});

The "$join" key holds an array of joins to perform, each join object has a key which denotes the collection name to pull data from, then matching criteria which in this case is to match purchase.itemId with the item._id. The three other keys are special operations (start with $) and indicate:

• $as tells the join what object key to store the join results in when returning the document
• $require is a boolean that denotes if the join must be successful for the item to be returned in the final find result
• $multi indicates if we should match just one item and then return, or match multiple items as an array

The result of the call above is:

[{
	"_id":1,
	"name":"Cat Litter",
	"price":200,
	"purchasedBy":[]
},{
	"_id":2,
	"name":"Dog Food",
	"price":100,
	"purchasedBy":[]
},{
	"_id":3,
	"price":400,
	"name":"Fish Bones",
	"purchasedBy":[]
},{
	"_id":4,
	"price":267,
	"name":"Scooby Snacks",
	"purchasedBy": [{
		"itemId":4,
		"user":"Fred Bloggs",
		"quantity":2
	}, {
		"itemId":4,
		"user":"Jim Jones",
		"quantity":1
	}]
},{
	"_id":5,
	"price":234,
	"name":"Chicken Yum Yum",
	"purchasedBy":[]
}]

Advanced Joins Using $where

Version => 1.3.455

If your join has more advanced requirements than matching against foreign keys alone, you can specify a custom query that will match data from the foreign collection using the $where clause in your $join.

For instance, to achieve the same results as the join in the above example, you can specify matching data in the foreign collection using the $$ back-reference operator:

itemCollection.find({}, {
	"$join": [{
		"purchase": {
			"$where": {
				"$query": {
					"itemId": "$$._id"
				}
			},
			"$as": "purchasedBy",
			"$require": false,
			"$multi": true
		}
	}]
});

The $$ back-reference operator allows you to reference key/value data from the document currently being evaluated by the join operation. In the example above the query in the $where operator is being run against the purchase collection and the back-reference will lookup the current _id in the itemCollection for the document currently undergoing the join.

Placing Results $as: "$root"

Suppose we have two collections "a" and "b" and we run a find() on "a" and join against "b".

$root tells the join system to place the data from "b" into the root of the source document in "a" so that it is placed as part of the return documents at root level rather than under a new key.

If you use "$as": "$root" you cannot use "$multi": true since that would simply overwrite the root keys in "a" that are copied from the foreign document over and over for each matching document in "b".

This query also copies the primary key field from matching documents in "b" to the document in "a". If you don't want this, you need to specify the fields that the query will return. You can do this by specifying an "options" section in the $where clause:

var result = a.find({}, {
	"$join": [{
		"b": {
			"$where": {
				"$query": {
					"_id": "$$._id"
				},
				"$options": {
					"_id": 0
				}
			},
			"$as": "$root",
			"$require": false,
			"$multi": false
		}
	}]
});

By providing the options object and specifying the "_id" field as zero we are telling ForerunnerDB to ignore and not return that field in the join data.

"id": 0

The options section also allows you to join b against other collections as well which means you can created nested joins.

Triggers

Version >= 1.3.12

ForerunnerDB currently supports triggers for inserts and updates at both the before and after operation phases. Triggers that fire on the before phase can also optionally modify the operation data and actually cancel the operation entirely allowing you to provide database-level data validation etc.

Setting up triggers is very easy.

Example 1: Cancel Operation Before Insert Trigger

Here is an example of a before insert trigger that will cancel the insert operation before the data is inserted into the database:

var fdb = new ForerunnerDB(),
	db = fdb.db("test"),
	collection = db.collection("test");

collection.addTrigger("myTrigger", db.TYPE_INSERT, db.PHASE_BEFORE, function (operation, oldData, newData) {
	// By returning false inside a "before" trigger we cancel the operation
	return false;
});

collection.insert({test: true});

The trigger method passed to addTrigger() as parameter 4 should handle these arguments:

Example 2: Modify a Document Before Update

In this example we insert a document into the collection and then update it afterwards. When the update operation is run the before update trigger is fired and the document is modified before the update is applied. This allows you to make changes to an operation before the operation is carried out.

var fdb = new ForerunnerDB(),
	db = fdb.db("test"),
	collection = db.collection("test");

collection.addTrigger("myTrigger", db.TYPE_UPDATE, db.PHASE_BEFORE, function (operation, oldData, newData) {
	newData.updated = String(new Date());
});

// Insert a document with the property "test" being true
collection.insert({test: true});

// Now update that document to set "test" to false - this
// will fire the trigger code registered above and cause the
// final document to have a new property "updated" which
// contains the date/time that the update occurred on that
// document
collection.update({test: true}, {test: false});

// Now inspect the document and it will show the "updated"
// property that the trigger added!
console.log(collection.find());

Please keep in mind that you can only modify a document's data during a before phase trigger. Modifications to the document during an after phase trigger will simply be ignored and will not be applied to the document. This applies to insert and update trigger types. Remove triggers cannot modify the document at any time.

Enabling / Disabling Triggers

Version >= 1.3.31

Enabling a Trigger

You can enable a previously disabled trigger or multiple triggers using the enableTrigger() method on a collection.

If you specify a type or type and phase and do not specify an ID the method will affect all triggers that match the type / phase.

Enable a Trigger via Trigger ID

db.collection("test").enableTrigger("myTriggerId");

Enable a Trigger via Type

db.collection("test").enableTrigger(db.TYPE_INSERT);

Enable a Trigger via Type and Phase

db.collection("test").enableTrigger(db.TYP