Sign Up for Free

RunKit +

Try any Node.js package right in your browser

This is a playground to test code. It runs a full Node.js environment and already has all of npm’s 400,000 packages pre-installed, including monogram with all npm packages installed. Try it out:

require("mongodb/package.json"); // mongodb is a peer dependency. var monogram = require("monogram")

This service is provided by RunKit and is not affiliated with npm, Inc or the package authors.

monogram v0.2.5

TAO (aspect-oriented) modeling for MongoDB


Action-based anti-ODM for MongoDB and Node.js

Read the intro blog post here.


const { connect } = require('monogram');
const db = await connect('mongodb://localhost:27017/test');



From an end developer perspective, monogram behaves just like the MongoDB Node.js driver. The key difference is that monogram converts collection functions into actions under the hood. Actions are an object representation of a function call.

    const Test = db.collection('Test');

    let called = 0;
    Test.pre(action => {
      // An _action_ is an object representation of a function call.
      // It has an `_id` property to uniquely identify it, and
      // some other properties:
      assert.deepEqual(_.omit(action, ['_id']), {
        collection: 'Test', // The name of the collection
        name: 'insertOne', // The name of the function called
        params: [{
          hello: 'world'
        }], // The parameters passed to the function
        chained: [] // Function calls chained onto this one

    await Test.insertOne({ hello: 'world' });

    assert.equal(called, 1);

Motivation: Logging

Monogram isn't an ODM/ORM like its uncle mongoose, It's a new abstraction entirely. You can call it an AOM, "action-object mapping". Why is this abstraction better? Consider the problem of logging all database operations to the console in an ODM. In mongoose, this is hard, because there's a lot of different types of middleware. In monogram, this is trivial, because all database operations are represented in a common form, actions, and all actions go through one pipeline.

    const Test = db.collection('Test');

    let called = 0;

    Test.action$.subscribe(action => {
      const params = action.params.
        map(p => util.inspect(p, { depth: 5 })).
        join(', ');
      const msg = `${action.collection}.${}(${params})`

        `Test.updateOne({ _id: 1 }, { '$set': { hello: 'world' } })`);

    await Test.updateOne({ _id: 1 }, {
      $set: { hello: 'world' }

    assert.equal(called, 1);

Enforcing Internal Best Practices

The purpose of monogram is to allow you to enforce best practices, not to prescribe best practices. Beginners are best served using a tool like mongoose, which has a lot of baked-in best practices to prevent you from shooting yourself in the foot. Monogram is more for advanced users who have established best practices they want to enforce. For example, here's how you would prevent users from calling updateOne() or updateMany() without any update operators, which would overwrite the document.

    const Test = db.collection('Test');

    let called = 0;

    // Will catch `updateOne()`, `updateMany()`, and `findOneAndUpdate()`
    // actions
    Test.pre(/update/i, action => {
      const update = action.params[1] || {};
      const keys = Object.keys(update);
      if (keys.length > 0 && !keys[0].startsWith('apos;)) {
        throw new Error('Not allowed to overwrite document ' +
          'using `updateOne()`, use `replaceOne() instead`');

    let threw = false;
    try {
      // Normally this would delete all properties on the document
      // other than `_id` and `overwrite`. This is expected behavior,
      // but you might want to disallow it. Monogram gives you a
      // framework to do so.
      await Test.updateOne({ _id: 1 }, { overwrite: 'woops!' });
    } catch (error) {
      threw = true;
      assert.equal(error.message, 'Not allowed to overwrite document ' +
        'using `updateOne()`, use `replaceOne() instead`');



RunKit is a free, in-browser JavaScript dev environment for prototyping Node.js code, with every npm package installed. Sign up to share your code.
Sign Up for Free