rongo.js

Rongo

What is Rongo ?

🔰️ A fully-typed Promise-based NodeJS driver for MongoDB.
💍️ A happy marriage between the relational and the NoSQL world.
🏃 An elegant way to escape subdocument hell without additional complexity.

---

• Overview
• Get started
• Features
  • Basic operations
  • Nest insertions
  • Nest filter queries
  • Cascade-delete
  • Search document references
  • Scan the database
  • Upcoming features
• Selectors
  • Understanding selectors
  • Syntax
• API

⚠️ This doc is still under construction

---

Overview

▶️ Create your Rongo handler :

import Rongo from "rongo.js";

const db = new Rongo("mongodb://localhost:27017/mydb");

▶️ Define a relation schema in just a few lines :

Author:
  foreignKeys:
    favoriteBooks.$:
      collection: Book
      onDelete: PULL
Book:
  foreignKeys:
    author:
      collection: Author
      onDelete: DELETE

db.schema("schema.yaml");

▶️ Cascade-insert related documents in one instruction :

const Book = db.collection("Book");

await Book.insert({
  title: "Harry Potter",
  author: {
    name: "J.K. Rowling",
    favoriteBooks: [
      {
        title: "Emma",
        author: {
          name: "Jane Austen",
          favoriteBooks: []
        }
      }
    ]
  }
});

The Book and Author collections then respectively contain :

[
  {
    "_id": ObjectID("606cbeab251aa79ab35ffd05"),
    "title": "Emma",
    "author": ObjectID("606cbf193aaa317e81b97150")
  },
  {
    "_id": ObjectID("606cbed349af304a1e828338"),
    "title": "Harry Potter",
    "author": ObjectID("606cbf3ac0680a044501108b")
  }
]

[
  {
    "_id": ObjectID("606cbf193aaa317e81b97150"),
    "name": "Jane Austen",
    "favoriteBooks": []
  },
  {
    "_id": ObjectID("606cbf3ac0680a044501108b"),
    "name": "J.K. Rowling",
    "favoriteBooks": [ObjectID("606cbeab251aa79ab35ffd05")]
  }
]

▶️ Nest related filter queries :

await Book.find({
  author: {
    $in: {
      name: "J.K. Rowling"
    }
  }
});

[
  {
    "_id": ObjectID("606cbed349af304a1e828338"),
    "title": "Harry Potter",
    "author": ObjectID("606cbf3ac0680a044501108b")
  }
]

▶️ Populate and aggregate results with a simple yet expressive syntax :

"Who wrote Harry Potter ?"

await Book.findOne({ title: "Harry Potter" }).select`author name`;

"J.K. Rowling"

"What's the title of J.K. Rowling's favorite books ?"

await Author.findOne({ name: "J.K. Rowling" }).select`favoriteBooks title`;

["Emma"]

"Who wrote J.K. Rowling's favorite books ?"

await Author.findOne({ name: "J.K. Rowling" })
  .select`favoriteBooks author name`;

["Jane Austen"]

"Get me the "Harry Potter" document, and partially populate its author field"

await Book.findOne({ title: "Harry Potter" }).select`{ *, author { name } }`;

{
  "_id": ObjectID("606cbed349af304a1e828338"),
  "title": "Harry Potter",
  "author": { "name": "J.K. Rowling" }
}

📌 Selectors are a powerful concept which allows you to do really a lot of useful things. More about them in the Selector section.

▶️ Cascade-delete related documents :

await Author.delete({ name: "Jane Austen" });

The Book and Author collections then respectively contain :

[
  {
    "_id": ObjectID("606cbed349af304a1e828338"),
    "title": "Harry Potter",
    "author": ObjectID("606cbf3ac0680a044501108b")
  }
]

[
  {
    "_id": ObjectID("606cbf3ac0680a044501108b"),
    "name": "J.K. Rowling",
    "favoriteBooks": []
  }
]

📌 By deleting the author "Jane Austen", her book "Emma" was deleted too, and so was its entry in J.K. Rowling's favorite book list.

▶️ And much more !

Quickly find foreign references to a given document, scan the database to look for dangling foreign keys, etc. The list keeps going on.

Things to keep in mind :

• The augmentation of the insertion and filter syntax to include relational stuff is a superset of the original syntax. Everything written using the conventional syntax will work with Rongo, unless you explicitly specify otherwise in your Rongo schema.
• You can opt-out the relational functionalities if you wish by playing with options, and just use Rongo as a regular MongoDB driver (like mongoose, monk, mongoist, etc.). For example :

  await Author.delete({ name: "Jane Austen" }, { propagate: false });