MonguitoDB

Utility to perform CRUD operations over the localStorage, sessionStorage, or any object implementing the Storage Interface defined by the W3C.

This library was inspired by MongoDB, and some of its functions are syntactically similar to how they are in Mongo, with some differences and limitations.

NOTE: This utility works synchronously.

Installation

Download the minified library (which is under 10KB) and include it in your html. Alternatively you can download the development version.

1<script src="monguito-db.min.js"></script>

Getting started

Initialize a new database instance with new MonguitoDB(storage, collections) where:

• storage: Is an object providing the storage mechanism. You can send localStorage or sessionStorage if the browser supports HTML5. Send null to use the default mechanism which stores collections in memory. Alternatively, you can send your own object implementing the Storage Interface defined by the W3C.
• collections: Is an array containing the names of the collections to be manipulated (analogous to tables in a relational database). You can send a single name, or an array of names if you want to manipulate several collections.

1// An object to perform CRUD operations over the HTML5 localStorage.
2var db = new MonguitoDB(localStorage, "orders");
3
4// An object to perform CRUD operations over the HTML5 sessionStorage.
5var db = new MonguitoDB(sessionStorage, ["orders", "users"]);
6
7// An object to perform CRUD operations over collections stored in memory.
8var db = new MonguitoDB(null, ["orders", "users"]);

Collection

A collection is a set of documents. It is equivalent to a table in the relational world, with the difference that a collection does not enforce a schema.

The following actions can be performed on a Collection: insert, update, remove, find, findOne, get, count.

Collections are initialized by MonguitoDB() constructor, they can't be initialized by yourself.

1// The following code shows how to reference collections initialized by
2// MonguitoDB() constructor.
3var db = new MonguitoDB(localStoraCoge, ["orders", "users"]);
4
5var ordersCollection = db.orders;
6var usersCollection  = db.users;

Collection.insert(obj) → {Document}

Inserts a new object into the collection and returns a reference to the inserted Document.

NOTE: _id property is the document's "primary key" wich is automatically assigned. It can be of two types:

1. Auto-numeric: when _id is omitted in the passed-in obj.
2. UUID: When _id is set to "uuid" in the passed-in obj.

Parameter	Type	Description
obj	object	Document to insert into the collection

Returns: Document

1var db = new MonguitoDB(localStorage, "orders");
2
3// case 1) _id will be automatically assigned as an auto-numeric value.
4var order = db.orders.insert({recipient: "Juan", total: 50});
5var documentId = order._id;
6
7// case 2) _id will be automatically assigned as an UUID.
8var order = db.orders.insert({_id: "uuid", recipient: "Juan", total: 50});
9var documentId = order._id;

Collection.update(query, obj) → {Cursor}

Updates one or several documents in the collection and returns a Cursor containing the updated documents.

NOTE: _id property can't be modified.

Parameter	Type	Description
query	object, function	Selection criteria for the update
obj	object	The modifications to apply (_id is omitted)

Returns: Cursor

1 var db = new MonguitoDB(localStorage, "orders");
2
3 // Updates a single document (that one matching _id = 1).
4 db.orders.update({_id: 1}, {status: "Delivered"});
5
6 // Updates several documents (those matching recipient = "Juan").
7 db.orders.update({recipient: "Juan"}, {status: "Delivered"});

Collection.remove(query)

Removes one or several documents from the collection.

NOTE: If no query is passed-in, all documents in the collection will be removed.

1var db = new MonguitoDB(localStorage, "orders");
2
3// Removes a single document (that one matching _id = 1).
4db.orders.remove({_id: 1});
5
6// Removes several documents (those matching recipient = "Juan").
7db.orders.remove({recipient: "Juan"});
8
9// Removes all documents in the collection.
10db.orders.remove();

Collection.find(query) → {Cursor}

Retrieves all documents in the collection matching the specified query. If no query is passed-in, all documents within the collection will be returned.

This function returns a Cursor that can be manipulated as an array plus the following actions: update, remove, find, findOne, get, first, last, sort, pretty, count.

Parameter	Type	Description
query	object, function	Specifies selection criteria

Returns: Cursor

1var db     = new MonguitoDB(localStorage, "orders");
2var orders = db.orders.find();
3
4// Each element in the cursor is of type Document
5orders.forEach(function (order) {
6   console.log(order.pretty());
7});
8
9// Applying conditions to retrieve the data.
10orders = db.orders.find({status: "Delivered"});
11orders = db.orders.find({status: "Delivered", seller: "Armani"});
12orders = db.orders.find(function (e) { return e.total > 700; });
13
14// Sorting the data.
15orders = db.orders.find().sort("seller");
16orders = db.orders.find().sort("seller, total");
17orders = db.orders.find().sort("seller ASC, total DESC");
18
19// Executing many actions in cascade.
20var firstOrder = db.orders.find().sort("total").first();
21var lastOrder  = db.orders.find().sort("total").last();
22
23// Printing the whole collection.
24console.log(db.orders.find().pretty());

Collection.findOne(query) → {Document | null}

Returns a Document that satisfies the specified query. If multiple documents satisfy the query, it will be returned the first document found (according to insertion order). If there is no matching document within the collection, it will be returned null.

The following actions can be performed on the returned document: update, remove, pretty.

Parameter	Type	Description
query	object, function	Specifies selection criteria

Returns: Document | null

1var db    = new MonguitoDB(localStorage, "orders");
2var order = db.orders.findOne({recipient: "Juan"});
3
4console.log(order.pretty());         // Prints the document.
5order.update({status: "Delivered"}); // Updates the document.
6order.remove();                      // Removes the document.
7
8// Using findOne() with a function criteria.
9var order = db.orders.findOne(function (e) { return e.total > 0; });

Collection.get(documentId) → {Document | null}

Gets the Document that matches the specified _id. If there is no matching document within the collection, it will be returned null.

The following actions can be performed on the returned document: update, remove, pretty.

NOTE: get() is faster than find() and findOne().

Parameter	Type	Description
documentId	number, string	Document _id

Returns: Document | null

1var db    = new MonguitoDB(localStorage, "orders");
2var order = db.orders.get(1);
3
4console.log(order.pretty());         // Prints the document.
5order.update({status: "Delivered"}); // Updates the document.
6order.remove();                      // Removes the document.

Collection.count() → {number}

Counts the number of documents in the collection.

Returns: number

1var db    = new MonguitoDB(localStorage, "orders");
2var count = db.orders.count();

Document

A document belongs to a Collection. It is a JSON structure composed by key-value pairs. It can be thought as a "record" belonging to a table in the relational world.

The following actions can be performed on a document: update, remove, pretty.

Documents are retrieved through methods in the Collection class, they can't be initialized by yourself.

1var db = new MonguitoDB(localStorage, "orders");
2
3// You get a reference to a Document when you insert one.
4var order = db.orders.insert({recipient: "Juan", total: 50});
5
6// You can get a Document with get() if you know its _id.
7var order = db.orders.get(1);
8
9// Individual elements retrieved from find() are of type Document.
10var order = db.orders.find({recipient: "Juan"})[0];
11
12// By using findOne you can get the first Document retrieved from a query.
13var order = db.orders.findOne({recipient: "Juan"});
14
15// You can also get a reference to a Document by using first() or last().
16var order = db.orders.find().first();

Document.update(obj) → {Document}

Updates the document in the storage.

NOTE: _id property can't be modified.

Parameter	Type	Description
obj	object	The modifications to apply (_id is omitted)

Returns: Document

1var db    = new MonguitoDB(localStorage, "orders");
2var order = db.orders.get(1);
3
4// Update with arguments.
5order.update({status: "Delivered"});
6
7// Update without arguments.
8order.status = "Delivered";
9order.update();

Document.remove()

Removes the document from the storage.

NOTE: Once you call remove() on a document, you can't perform remove() or update() on the document anymore, because an exception will be thrown.

1var db    = new MonguitoDB(localStorage, "orders");
2var order = db.orders.get(1);
3
4order.remove();

Document.pretty() → {string}

Gets a "pretty" JSON representation of the document.

Returns: string

1var db    = new MonguitoDB(localStorage, "orders");
2var order = db.orders.get(1);
3
4console.log(order.pretty());

Cursor

A cursor is a set of documents. It can be manipulated as an array plus the following actions: update, remove, find, findOne, get, first, last, sort, pretty, count.

Cursors are initialized by Collection.find(), they can't be initialized by yourself.

1var db     = new MonguitoDB(localStorage, "orders");
2var cursor = db.orders.find({recipient: "Juan"});

Cursor.update(obj) → {Cursor}

Updates all documents in the cursor (changes are applied both in the cursor and the storage).

NOTE: _id property can't be modified.

Parameter	Type	Description
obj	object	The modifications to apply (_id is omitted)

Returns: Cursor

1var db     = new MonguitoDB(localStorage, "orders");
2var cursor = db.orders.find({recipient: "Juan"});
3
4// Updates all orders belonging to "Juan" with status "Delivered".
5cursor.update({status: "Delivered"});

Cursor.remove()

Removes all documents in the cursor (changes are applied both in the cursor and the storage).

NOTE: Once you call remove() on a cursor the cursor will be empty.

1var db     = new MonguitoDB(localStorage, "orders");
2var cursor = db.orders.find({recipient: "Juan"});
3
4// Removes all orders belonging to "Juan".
5cursor.remove();

Cursor.find(query) → {Cursor}

Retrieves all documents within the cursor that match the specified query.

NOTE: This function creates and returns a new cursor (the original one won't be modified).

Parameter	Type	Description
query	object, function	Specifies selection criteria

Returns: Cursor

1var db     = new MonguitoDB(localStorage, "orders");
2var cursor = db.orders.find({recipient: "Juan"});
3
4// Gets all orders belonging to "Juan" with status "Pending".
5var pending = cursor.find({status: "Pending"});
6
7// Gets all orders belonging to "Juan" with total >= 1000.
8var expensive = cursor.find(function (e) { return e.total >= 1000; });

Cursor.findOne(query) → {Document | null}

Returns a Document within the cursor matching the specified query. If multiple documents satisfy the query, it will be returned the first document found. If there is no matching document within the cursor, it will be returned null.

Parameter	Type	Description
query	object, function	Specifies selection criteria

Returns: Document | null

1var db     = new MonguitoDB(localStorage, "orders");
2var cursor = db.orders.find({recipient: "Juan"});
3
4// Gets the order belonging to "Juan" with number "107-1".
5var order = cursor.findOne({number: "107-1"});
6
7// Another way to do the same above.
8var order = cursor.findOne(function (e) { return e.number === "107-1"});

Cursor.get(documentId) → {Document | null}

Gets the Document within the cursor matching the specified _id. If there is no matching document within the cursor, it will be returned null.

Parameter	Type	Description
documentId	number, string	Document _id

Returns: Document | null

1var db     = new MonguitoDB(localStorage, "orders");
2var cursor = db.orders.find({recipient: "Juan"});
3
4// Gets the order belonging to "Juan" with _id = 1.
5var order = cursor.get(1);

Cursor.first() → {Document | null}

Returns the first Document within the cursor. If the cursor is empty, it will be returned null.

Returns: Document | null

1var db     = new MonguitoDB(localStorage, "orders");
2var cursor = db.orders.find({recipient: "Juan"});
3
4// Gets the first order belonging to "Juan".
5var order = cursor.first();

Cursor.last() → {Document | null}

Returns the last Document within the cursor. If the cursor is empty, it will be returned null.

Returns: Document | null

1var db     = new MonguitoDB(localStorage, "orders");
2var cursor = db.orders.find({recipient: "Juan"});
3
4// Gets the last order belonging to "Juan".
5var order = cursor.last();

Cursor.sort(sortExpression) → {Cursor}

Sorts the cursor and returns a reference to the new sorted cursor.

NOTE: This function creates and returns a new cursor (the original one won't be modified).

Parameter	Type	Description
sortExpression	string	Sort expression (You can use ASC or DESC to specify sort direction

Returns: Cursor

1var db     = new MonguitoDB(localStorage, "orders");
2var cursor = db.orders.find({recipient: "Juan"});
3
4// Sorts the documents by seller (Default sort direction is ascending).
5var orders = cursor.sort("seller");
6
7// Sorts the documents by seller and total.
8var orders = cursor.sort("seller, total");
9
10// Sorts the documents by seller (ascending) and total (descending).
11var orders = cursor.sort("seller ASC, total DESC");

Cursor.pretty() → {string}

Gets a "pretty" JSON representation of the cursor.

Returns: string

1var db     = new MonguitoDB(localStorage, "orders");
2var cursor = db.orders.find({recipient: "Juan"});
3
4// Prints all orders belonging to "Juan".
5console.log(cursor.pretty());

Cursor.count() → {number}

Counts the number of documents within the cursor.

Returns: number

1var db     = new MonguitoDB(localStorage, "orders");
2var cursor = db.orders.find({recipient: "Juan"});
3
4// Counts the number of orders belonging to "Juan"
5var count  = cursor.count();

TODO List

• Full demo page
• Pagination
• Import data
• Agregation framework
• Full text search
• Replication

Creator

Juan Cuartas

• http://juancuartas.com
• https://twitter.com/juancuartas

Copyright and license

Code and documentation released under the MIT license