ForerunnerDB

Version 3.0 is Coming!

Many of you use ForerunnerDB in your work and have given lots of feedback to me about getting some new features / functionality into the next version. You can see the active work on this endeavour over at https://github.com/Irrelon/forerunnerdb-core

ForerunnerDB 3.0 is being built in a completely modular fashion with extensibility at heart. Things like better persistent storage, exotic index support, different query language support etc are all going to be much simpler. It's nowhere near ready for prime time right now but if you feel like checking out the core functionality, head over to that repo above and check out what's there. With ❤ from Rob.

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: [email protected]

Version 2.0.24

TravisCI Build Test Status

Master Dev

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):

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.