Mongorito

<h1 align="center"> <br> <img width="400" src="media/logo.png"> <br> <br> </h1>

Lightweight and flexible MongoDB ODM for Node.js apps based on Redux.

Features

Flexible

Mongorito is based on Redux, which opens the doors for customizing literally everything - from model's state (reducers) to the behavior of core methods, like set(), save() or find().

Each model instance has a separate Redux store, which ensures isolation between other models and easy extensibility.

No schemas

If MongoDB doesn't enforce schemas, why would Mongorito do? Enjoy the schema-free data management with Mongorito the same way you do in mongo console.

Lightweight

Mongorito is betting on 3rd-party plugins to deliver extra functionality to developers. Mongorito ships with a barebones model with basic get/set, save/remove and querying functionality and let's you be in control of what's included and what's not.

Mongorito is basically a tiny Redux-based application, which uses the official MongoDB driver and mquery for querying. Not that amount of lines are relevant when measuring complexity, but each file (module) is less than 300 lines. Check out the source code and see for yourself!

Quick overview

const {Database, Model} = require('mongorito');

const db = new Database('localhost/blog');
await db.connect();

class Post extends Model {}

db.register(Post);

const post = new Post({
	title: 'Steve Angello rocks',
	author: {
		name: 'Emma'
	}
});

await post.save();

post.set('author.name', 'Rick');
await post.save();

await db.disconnect();

Note: await won't work at top level, it's used to reduce the complexity of an example.

Installation

$ npm install --save mongorito

Contents

• Connection
• Models
• • Creating a model
• • Working with fields
• • Saving or removing documents
• • Incrementing fields
• • Embedding other models
• • Configuration
• Queries
• Plugins
• • Using plugins
• • Writing plugins
• • Extending model with new methods
• • Modifying model's state
• • Changing behavior using middleware
• Migrating from legacy version

Connection

Mongorito exports several own classes, as well as a few properties from the MongoDB driver:

const {
	Database,
	Model,
	Timestamp,
	ObjectId,
	MinKey,
	MaxKey,
	DBRef,
	Long
} = require('mongorito');

Database and Model are Mongorito's own exports, all the other ones are exported straight from mongodb package for convenience. Normally, you'd need only Database, Model and ObjectId.

To connect, initialize a Database, which accepts a MongoDB connection string and an optional configuration which will be passed to mongodb's connect function.

To connect and disconnect use connect()/disconnect() methods. Both returns a Promise.

For convenience, await will be used in all examples below, even though it doesn't work at top level.

const {Database, Model} = require('mongorito');

const db = new Database('localhost/blog', {
	reconnectTries: 5
});

await db.connect();
await db.disconnect();

You don't have to wait until connection establishes to perform operations. Mongorito automatically executes pending operations once connection is up.

Models

Creating a model

Model is the connection between your data and a database. Each model represents a single collection. Model is a simple class, which doesn't even need to have any properties or methods.

class Post extends Model {}

For Post model to work and be aware of the database it's connected to, make sure to register it in the database we created earlier.

db.register(Post);

That's it, the Post model is good to go!

Working with fields

To create a new document, create an instance of Post model.

const post = new Post();

Model's constructor also accepts an object of fields to instantiate the document with:

const post = new Post({
	title: 'Great post',
	author: {
		name: 'Sarah'
	}
});

Note, documents can contain nested fields and even models, just like in MongoDB.

To get one or all fields from the post document, use a get() method.

const title = post.get('title');
//=> "Great post"

const author = post.get('author.name');
//=> "Sarah"

const data = post.get();
//=>
//  {
//    title: "Great post"
//    author: {
//      name: "Sarah"
//    }
//  }

Similarly, use set() to update fields:

// update fields one by one
post.set('title', 'Amazing post');
post.set('author.name', 'Monica');

// or all at once
post.set({
	title: 'Amazing post',
	author: {
		name: 'Monica'
	}
});

To remove a field, use unset():

// unset single fields
post.unset('title');
post.unset('author.name');

// or multiple fields at once
post.unset(['title', 'author.name']);

Saving or removing documents

To create or update documents, simply call save(). Even though Mongorito differentiates these two operations internally, you don't have to care about that! Mongorito also infers the collection name from the model, so the instances of the model Post will be saved to posts collection.

await post.save();

When a document is saved, an _id field is automatically added.

post.get('_id');
//=> ObjectId("5905cb6b543c3a50e03e810d")

To remove a document, use remove().

await post.remove();

To remove multiple documents, use remove() on the model itself with a query as an argument.

await Post.remove({good: false});

Incrementing fields

Mongorito also provides a handy increment() method to increment or decrement numerical fields:

const post = new Post({
	views: 0
});

await post.increment('views');

post.get('views');
//=> 1

You can also supply a value to increment a field by a specific amount.

await post.increment('views', 2);

post.get('views');
//=> 3

Multiple fields can be incremented at once, too.

const post = new Post({
	views: 10,
	comments: 10
});

await post.increment({
	views: 2,
	comments: 5
});

post.get('views');
//=> 12

post.get('comments');
//=> 15

Embedding other models

Just like MongoDB, Mongorito allows to effortlessly embed other models. They're transparently converted between JSON and Mongorito models.

To embed models, use embeds() method on the model itself to help Mongorito with the model serialization when saving/reading from the database. embeds() method accepts a field name, where the embedded document (or array of documents) resides.

Here's the quick overview on how it works. Note, that model registering via register() is skipped in the following example.

class Post extends Model {}
class Author extends Model {}
class Comment extends Model {}

Post.embeds('author', Author);
Post.embeds('comments', Comment);

const post = new Post({
	title: 'Great post',
	author: new Author({name: 'Steve'}),
	comments: [new Comment({body: 'Interesting!'})]
});

await post.save();

The above post will be saved to the database as:

{
	"title": "Great post",
	"author": {
		"name": "Steve"
	},
	"comments": [
		{
			"body": "Interesting!"
		}
	]
}

You can also just pass objects instead of model instances and Mongorito will take care of that too.

const post = new Post({
	title: 'Great post',
	author: {
		name: 'Steve'
	},
	comments: [{
		body: 'Interesting!'
	}]
});

When that document will be retrieved from the database next time, all embedded documents will be wrapped with their corresponding models.

const post = await Post.findOne();

const author = post.get('author');
//=> Author { name: "Steve" }

author.get('name');
//=> "Steve"

Configuration

Using a different collection name

In case you need to store documents in a custom collection, you can override the default one using collection() method.

class Post extends Model {
	collection() {
		return 'awesome_posts';
	}
}

Queries

Mongorito uses mquery to provide a simple and comfortable API for querying. It inherits all the methods from mquery with a few exceptions, which will be documented below. For documentation, please check out mquery's API - https://github.com/aheckmann/mquery.

Here's a quick overview of how querying works in Mongorito. All documents returned from queries are automatically wrapped into their models.

// find all posts
await Post.find();

// find all amazing posts
await Post.find({amazing: true});
await Post.where('amazing', true).find();

// find 5 recent posts
await Post
	.limit(5)
	.sort('created_at', 'desc')
	.find();

// find one post
await Post.findOne({incredible: 'yes'});

// count posts
await Post.count({super: false});

Plugins

Using plugins

To use a 3rd-party plugin, all you have to do is to call use() method.

const timestamps = require('mongorito-timestamps');

db.use(timestamps());

This will apply mongorito-timestamps to models registered after that.

If you want to apply the plugin to a specific model only, call it