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 , or .
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();
Note: await won't work at top level, it's used to reduce the complexity of an example.
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 use connect() method, which 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');await db.connect();
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.
// update fields one by onepost.set('title', 'Amazing post');post.set('author.name', 'Monica');// or all at oncepost.set({ title: 'Amazing post', author: { name: 'Monica' }});
To remove a field, use unset():
// unset single fieldspost.unset('title');post.unset('author.name');// or multiple fields at oncepost.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.
const post = new Post({ views: 10, comments: 10});await post.increment({ views: 2, comments: 5});post.get('views');//=> 12post.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();
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 postsawait Post.find();// find all amazing postsawait Post.find({amazing: true});await Post.where('amazing', true).find();// find 5 recent postsawait Post .limit(5) .sort('created_at', 'desc') .find();// find one postawait Post.findOne({incredible: 'yes'});// count postsawait Post.count({super: false});
Plugins
Using plugins
To use a 3rd-party plugin, all you have to do is to call use() method.
If you want to apply the plugin to a specific model only, call it on the model itself.
Post.use(timestamps);
Writing plugins
A plugin is simply a function that accepts a model. A familiarity with Redux and its concepts will help you tremendously with writing plugins.
const myPlugin = model => { // do anything with model (Post, in this case)};Post.use(myPlugin);
Feel free to assign new methods to the model or instances, add new middleware, modify the model's state and anything that comes to your mind.
Extending model with new methods
Here's an example of adding a class method and an instance method to a Post model.
const extendPost = Post => { Post.findRecent = function () { return this .limit(5) .sort('created_at', 'desc') .find(); }; Post.prototype.makeAmazing = function () { this.set('amazing', true); };};Post.use(extendPost);const post = new Post();post.makeAmazing();post.get('amazing');//=> trueconst posts = await Post.findRecent();//=> [Post, Post, Post]
Modifying model's state
If you plugin needs to have its own state, you can modify the model's reducer using modifyReducer() method. It accepts a function, which receives the existing reducer shape as an argument and should return a new object with added reducers.
Middleware can be used to change or modify the behavior of model's operations. You can interact with everything, from get/set operations to queries.
To add plugin's custom middleware to the default middleware stack, return it from the plugin function.
const myPlugin = () => { return store => next => action => { // middleware code... };};
Obviously, to detect what kind of action is being handled, you need to be aware of Mongorito's action types.
const {ActionTypes} = require('mongorito');const myPlugin = () => { return store => next => action => { if (action.type === ActionTypes.SET) { // alter set() behavior } return next(action); };};
Again, the middleware is identical to the middleware you're used to when writing apps with Redux. There are only 2 new properties added to the store:
model - instance of the model (document) the middleware is currently running in. If middleware is running at the model level (without instantiated model), it will be undefined.
modelClass - model class (Post, for example).
Here's an example on how to access all props of the store:
const myPlugin = () => { return ({getState, dispatch, model, modelClass}) => next => action => { // `getState()` and `dispatch()` are from Redux itself // `model` is `post` // `modelClass` is `Post` return next(action); };};Post.use(myPlugin);const post = new Post();await post.save();