jclo / picodb

A tiny in-memory database (MongoDB like) that stores JSON documents

PicoDB

PicoDB is an in-memory database that stores JSON like documents. It runs both on Node.js and in the ES6 compliant browsers.

PicoDB manages the documents as MongoDB for a collection. It provides a flexible API (MongoDB like) to insert, update, delete and find documents.

PicoDB is useful when you want to manage documents directly inside your Web App.

Nota: From PicoDB 1.x IE browsers are not supported anymore. PicoDB 0.12 is the latest version that is IE compliant.

Quick Startup

Documents

A document is a Javascript literal object. It is similar to a JSON object. A set of key-value pairs.

When a document is inserted into the database, it gets an unique id that is a string of 16 characters. Thus, a document into the database looks like:

{ _id: 'atpl4rqu8tzkt9', name: { first: 'John', last: 'Doe' }, email: '[e-mail]' }

Create the database

On Node.js:

const PicoDB = require('picodb');
const db = PicoDB();

In the browser:

const db = PicoDB();

Listen for a Response

There is now three ways to listen a response from a PicoDB instance:

• Via Callback:

db.find({}).toArray((err, resp) => {
    // your code here
});

• Via then/catch

db.find({}).toArray()
    .then((resp) => {
      // your code here
    })
    .catch((err) => {
      // your code here
    });

• Via async/await

async function fn() {
    ...
    const resp = await db.find({}).toArray();
    ...
}

Insert documents

PicoDB provides two methods for inserting documents.

A method for inserting one document:

// doc contains the inserted document with its unique id.
const doc = await db.insertOne({ a: 1 });

And a method for inserting a set of documents:

// docs contains the inserted documents with their unique ids.
const docs = await db.insertMany([{ a: 1 }, { a: 2, b: 2 }]);

Update documents

PicoDB provides two methods for updating documents.

A method for updating the first document that matches the query:

// doc contains the updated document.
const doc = await db.updateOne({ a: 1 }, { c: 'aaa' });

And a method for updating all the documents that match the query:

// docs contains the updated documents.
const docs = await db.updateMany({ a: 1 }, { c: 'aaa' });

The first method replaces the first document (the oldest one) into the database that contains the key-value pair { a: 1 } by the new document { c: 'aaa' } while the second method replaces all the documents that contain this key-value pair by the new document.

These methods replace the document(s) but they do not alter their _id.

The update methods provide the two operators $set and $unset for a finest update granularity.

The following operation:

const docs = await db.updateOne({ a: 1 }, { $set: { c: 'new' }});

selects the first document into the database that contains the field a = 1 (or the key-value pair a = 1) and replaces the value of the field c by new or adds the field if it doesn't exist.

while the following operation:

const docs = await db.updateOne({ a: 1 }, { $unset: { c: 'aaa' }});

removes the field c = 'aaa'.

Delete documents

PicoDB provides two methods for deleting documents.

A method for deleting the first document that matches the query:

// num contains the number of deleted documents (here 0 or 1).
const num = await db.deleteOne({ a: 1 });

And a method for deleting all the documents that match the query:

// num contains the number of deleted documents.
const num = await db.deleteMany({ a: 1 });

Count documents

PicoDB provides one method to count the number of the documents into the database that match the query.

// num contains the number of documents that match the query.
const count = await db.count({ a: 1 });

Find documents

PicoDB provides one method to dump the documents that match the query.

The following instruction:

const docs = await db.find({}).toArray();

dumps all the documents into the database as the query {} does not filter anything.

While the instruction:

// docs is an array of documents that match the query.
const docs = await db.find({ a: 1 }).toArray();

dumps the documents that contain the field a with the value 1.

Select the fields to extract

PicoDB allows selecting the fields to extract from the database.

The following instruction:

const docs = await db.find({}, { c: 1, d: 1 }).toArray();

dumps all the documents but extracts only the fields _id, c and d. The field _id is extracted by default. You can reject it by adding _id: 0 to the expression:

// docs is an array of documents that match the query.
const docs = await db.find({}, { _id: 0, c: 1, d: 1 }).toArray();

Instead of defining the fields to extract, you can set the fields to exclude. This instruction:

// docs is an array of documents that match the query.
const docs = await db.find({}, { c: 0, d: 0 }).toArray();

dumps all the documents with all the fields except c and d.

Query Operators

PicoDB provides a subset of MongoDB's Query Operators like $eq, $gt, $gte, $lt, etc.

These operators allow more sophisticated queries.

The following instruction:

const docs = await db.find({ a: { $gt: 1 }, b: { $lt : 6 }}).toArray();

dumps all the documents with the field a having a value greater than 1 AND the field b having a value lower than 6.

Listen

PicoDB provides, through a plugin, the following custom events change, insert, update and delete that are fired when a document into the database is modified.

The following instruction:

const docs = await db.on('change');

is executed when documents are inserted, updated or deleted.

This option uses the NPM package @mobilabs/messenger. You need to install it before instantiating PicoDB like that:

import Messenger from 'path/to/@mobilabs/messenger';

PicoDB.plugin({ messenger: Messenger });
const db = PicoDB();

API

Constructor

Constructor   | Description

PicoDB        | Creates the PicoDB object (without the operator new).

Static Methods

Static methods | Description

plugin         | Adds and external library.

Methods

PicoDB implements the following methods:

Method     | Description

count      | Counts number of matching documents into the db.
deleteMany | Deletes multiple matching documents into the db.
deleteOne  | Deletes the first matching document into the db.
insertMany | Inserts an array of documents into the db.
insertOne  | Inserts one document into the db.
updateMany | Updates multiple matching documents into the db.
updateOne  | Updates the first matching documents into the db.
find       | Finds multiple matching documents into the db.
toArray    | Returns the array of documents selected with the find method.
on         | Adds an event listener (alias of addEventListener).
one        | Adds an event listener that fires once (alias of addOneTimeEventListener).
off        | Removes the event listener (alias of removeEventListener).

Query Operators

Comparison Operators

PicoDB implements the following Comparison Operators:

Operator | Description

$eq      | Matches values that are equal to a specified value.
$gt      | Matches values that are greater than a specified value.
$gte     | Matches values that are greater than or equal to a specified value.
$lt      | Matches values that are less than a specified value.
$lte     | Matches values that are less than or equal to a specified value.
$ne      | Matches all values that are not equal to a specified value.
$in      | Matches any of the values specified in an array.
$nin     | Matches none of the values specified in an array.

Element Operators

Operator | Description

$exists  | Matches documents that have the specified field.

Logical Operators

Operator | Description

$and     | Joins query clauses with a logical AND returns all documents that match the conditions of either clause.
$or      | Joins query clauses with a logical OR returns all documents that match the conditions of either clause.
$not     | Inverts the effect of a query expression and returns documents that do not match the query expression.

Geospatial Operators

Operator       | Description

$geoWithin     | Selects geometries within a bounding GeoJSON geometry.
$geoIntersects | Selects geometries that intersect with a GeoJSON geometry.
$near          | Selects geometries that are inside limits on the Earth sphere.

$geoWithin and $geoIntersects GeoJSON geometries could only by Polygon and MultiPolygon.

geoWithin supports Point, LineString, MultiPoint, MultiLineString and Polygon geometries.

geoIntersects supports LineString and Polygon geometries.

Geometry Specifiers

$geoWithin could be used with the legacy shape operators:

$box           | Specifies a rectangle to return documents that are within the rectangle.
$polygon       | Specifies a rectangle to return documents that are within the polygon.
$center        | Specifies a circle to return documents that are within the circle.
$centerSphere  | Specifies a earth-like sphere to return documents that are within the sphere.

$near could be used with the following operators:

$minDistance   | Specifies a minimum distance to limit the results of queries.
$maxDistance   | Specifies a maximum distance to limit the results of queries

$minDistance and $maxDistance specify the distance in meters.

Update Operators

Field Operators

Operator     | Description

$inc         | Increments the value of the field by the specified amount.
$mul         | Multiplies the value of the field by the specified amount.
$rename      | Renames a field.
$set         | Sets the value of a field in a document or adds it.
$unset       | Removes the specified field from a document.
$min         | Updates the field if the specified value is less than the existing field value.
$max         | Updates the field if the specified value is greater than the existing field value.
$currentDate | Sets the value of a field to current date.

Array Operators

Operator     | Description

$pop         | Removes the first or last item of an array.
$pullAll     | Removes all matching values from an array.
$pull        | Removes all the array elements that match a specified query.
$push        | Adds an item to an array.

Array Update Operator Modifiers

$push operator can be used with the following modifiers:

Operator     | Description

$each        | Modifies the $push and operator to append multiple items for array updates.
$slice       | Modifies the $push operator to limit the size of updated arrays.
$position    | Modifies the $push operator to specify the position in the array to add elements.

Array Update Comparison Operators

pull operator can be used with the following comparison operators:

Operator     | Description

$eq          | Matches values that are equal to a specified value.
$gt          | Matches values that are greater than a specified value.
$gte         | Matches values that are greater than or equal to a specified value.
$lt          | Matches values that are less than a specified value.
$lte         | Matches values that are less than or equal to a specified value.
$ne          | Matches all values that are not equal to a specified value.
$in          | Matches any of the values specified in an array.
$nin         | Matches none of the values specified in an array.

Events (optional)

Event type   | Description

change       | Fires when a document is modified with the methods insert, update or delete.
insert       | Fires when a document is inserted into the db.
update       | Fires when one or multiple documents are updated into the db.
delete       | Fire when one or multiple documents are deleted from the db.

License

MIT.