npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

@onehilltech/blueprint-mongodb

v4.76.1

Published

Blueprint.js module for MongoDB

Downloads

617

Readme

blueprint-mongodb

A Blueprint.js module for MongoDB

npm version Build Status Dependencies Coverage Status

Installation

npm install @onehilltech/blueprint-mongodb --save

Usage

Configuration

Define the mongodb.js configuration file in your Blueprint.js application.

// app/configs/mongodb.js

module.exports = {
  connections: {
    $default: {
      uri: 'mongodb://localhost/tutorial',
      seed: [true|false],    // seed the database connection [default=false]
      options : {            // mongoose connection options
        
      }
    },
    
    connection2: {
      // ...
    }
  }
};

Models

Models represent the different collections stored in the MongoDB database. The models are defined using Mongoose schemas.

// app/models/Person.js
const mongodb = require ('@onehilltech/blueprint-mongodb');
const { Schema } = mongodb;

// use mongodb.Types to access mongoose.Types

const schema = mongodb.Schema ({
  first_name: {type: String, required: true, trim: true},
  last_name : {type: String, required: true, trim: true}
});

module.exports = mongodb.models ('person', schema, 'blueprint_people');

All models are defined on the default connection unless stated otherwise. To define a models on a different connection, use the modelOn() function where the first parameter is the name of the connection as defined in mongodb.js followed by the same parameters for the models() function.

Resources

Resource Model

A resource models is a models that includes an extra _stats property that details when the resource is created and updated. Both fields are managed automatically. You define a resource models similar to how you define a regular models. Instead of using the models() function, you use the resource() function.

// app/models/Person.js
const mongodb = require ('@onehilltech/blueprint-mongodb');
const { Schema } = mongodb;

// use mongodb.Types to access mongoose.Types

const schema = mongodb.Schema ({
  first_name: {type: String, required: true, trim: true},
  last_name : {type: String, required: true, trim: true}
});

module.exports = mongodb.resource ('person', schema, 'blueprint_people');

Soft Deletes

A soft delete is when the models is marked as deleted, but remains in the database. This is important if you want to still access the models in references. Soft delete is only available on resource models.

You add soft delete to a resource by setting the softDelete option to true when you are creating the schema.

const schema = mongodb.Schema ({
  first_name: {type: String, required: true, trim: true},
  last_name : {type: String, required: true, trim: true}
}, {softDelete: true});

module.exports = mongodb.resource ('person', schema, 'blueprint_people');

Now, when the person resource models is created, the _stat property will contain a deleted_at property. This property will be managed internally by the resource controller.

Resource Controller

The ResourceController is a default implementation of a resource controller that integrates with the Blueprint.js architecture. The ResourceController can be used as-is, or extended to add domain-specific customizations.

const { ResourceController } = require ('@onehilltech/blueprint-mongodb');
const { models } = require ('@onehilltech/blueprint');

/**
 * @class PersonController 
 * 
 * Resource controller for the person resource models.
 */
module.exports = ResourceController.extend ({
  Model: model ('person')
});

The resource controller exposes the following actions:

| Action | HTTP method | Path | Body | Response |--------------|-------------|-----------------|----------------------------|-----------------------------------| | create | POST | /resource | {<resource>: { values }} | {<resource>: { values }} | | getOne | GET | /resource/:rcId | N/A | {<resource>: { values }} | | getAll | GET | /resource | N/A | {<plural-resource>: { values }} |
| count | GET | /resource/count | N/A | {count: n} |
| update | PUT | /resource/:rcId | {<resource>: { values }} | {<resource>: { values }} | | delete | DELETE | /resource/:rcId | N/A | true or false |

For example, the PersonController exposes the following actions:

| Action | HTTP method | Path | Body | Response |---------|-------------|---------------| ----------------------------|-----------------------------------| | create | POST | /person | {person: { first_name: 'James', last_name: 'Hill }} | {person: {_id: 'id', first_name: 'James', last_name: 'Hill' }} | | getOne | GET | /person/id | N/A | {person: {_id: 'id', first_name: 'James', last_name: 'Hill' }} | | getAll | GET | /person | N/A | {persons: [{_id: 'id', first_name: 'James', last_name: 'Hill' }]} |
| count | GET | /person/count | N/A | {count: n} |
| update | PUT | /person/id | {person: { first_name: 'John' }} | {person: {_id: 'id', first_name: 'John', last_name: 'Hill }} | | delete | DELETE | /person/id | N/A | true or false |

Messaging Framework. All actions on the default implementation of the ResourceController will generate the following events on Blueprint.js messaging framework.

| Action | Event | Example | |--------|-------|---------| | create | [prefix.][name].created | [prefix.]person.created | | update | [prefix.][name].updated | [prefix.]person.updated | | delete | [prefix.][name].deleted | [prefix.]person.deleted |

The prefix in the event name is optional. It is defined by the eventPrefix property passed to the ResourceController constructor.

Adding Domain-specific Behavior

Each method in the ResourceController returns an action that can be extended to add domain-specific behavior. For example, you may want to do pre and post processing before and after the models is created, respectively. It is as simple as extending the action in your subclass of the ResourceController, and overloading the appropriate methods.

const { ResourceController } = require ('@onehilltech/blueprint-mongodb');
const { model } = require ('@onehilltech/blueprint');

/**
 * @class PersonController 
 * 
 * Resource controller for the person resource models.
 */
module.exports = ResourceController.extend ({
  Model: model ('person'),
  
  create () {
    return this._super.call (this, ...arguments).extend ({
      prepareDocument (req, doc) {
        doc.user = req.user._id;
        return doc;
      }
    });
  }
});

The following is a list of the actions, and the method that can be overloaded in their order of execution.

  • create
    • prepareDocument (req, doc)
    • preCreateModel (req)
    • createModel (req, doc)
    • postCreateModel (req, models)
    • prepareResponse (req, res, result)
  • getOne
    • getId (req, id)
    • getProjection(req)
    • getOptions (req, options)
    • preGetModel (req)
    • getModel (req, id, projection, options)
    • postGetModel (req, models)
    • prepareResponse (req, res, result)
  • getAll
    • getFilter (req, query)
    • getProjection (req)
    • getOptions (req, options)
    • preGetModels (req)
    • getModels (req, filter, projection, options)
    • postGetModels (req, models)
    • .prepareResponse (req, res, result)
  • update
    • getId (req, id)
    • getUpdate (req, update)
    • getOptions (req, options)
    • preUpdateModel (req)
    • updateModel (req, id, update, options)
    • postUpdateModel (req, models)
    • prepareResponse (req, res, result)
  • delete
    • getId (req, id)
    • preDeleteModel (req)
    • deleteModel (req, id)
    • postDeleteModel (req, models)
    • prepareResponse (req, res, models, result)
  • count
    • getFilter (req, filter)
    • preCountModels (req)
    • getCount (req, filter)
    • postCountModels (req, count)
    • prepareResponse (req, res, result)

You can return a Promise the overloaded method if you need to perform asynchronous execution.

GridFSController

The GridFSController is a Blueprint.js resource controller designed for GridFS in MongoDB. The GridFSController supports the following operations out-of-the-box:

  • create
  • getOne
  • delete

Currently, it does not support getting multiple resources and updating an existing resource.

Because GridFS is designed to store large files, the GridFSController assumes the client is uploading a file, which can be a multi-part file. The controller handles this concern automatically. It's just your responsibility to inform the controller of the parameter used for the upload, and what connection on the database to use for GridFS. Below is an example GridFSController for storing images that use the default connection.

const { GridFSController } = require ('@onehilltech/blueprint-mongodb');

/**
 * @class ImageController
 */
module.exports = GridFSController.extend ({
  // name of resource
  name: 'image',       
});

This controller will extract the uploaded file from the image parameter. In addition, it will create collections named image.files and image.chunks in the database associated with the connection.

See GridFSController for the optional properties to configure the controller's behavior.

Seeding Database for Testing

The @onehilltech/blueprint-mongodb module provides support for seeding the database defined in your connection. When paired with fakerjs, you can create realistic environments/scenario for development and testing purposes.

You cannot seed a production database because seeding can be a destructive operation.

The database seed is located (or placed) in app/seeds/mongodb. The database seed is defined using dab. Last, the name of the seed file matches the name of the database connection you want to seed. Using our example Person schema from above, here is a dab definition that seeds the default database connection with 2 people.

// app/seeds/mongodb/default.js

const { Seed } = require ('@onehilltech/blueprint-mongodb');

module.exports = Seed.extend ({
  model () {
    return {
      person: [
        { first_name: 'Tom', last_name: 'Thumb' },
        { first_name: 'Jill', last_name: 'Wilson' } 
      ]
    }
  }
});

Here is another example of using the dab.times generator and fakerjs to add 50 people to the database.

// app/seeds/mongodb/default.js

const { Seed } = require ('@onehilltech/blueprint-mongodb');
const dab = require ('@onehilltech/dab');
const faker = require ('faker');


module.exports = Seed.extend ({
  model () {
    return {
      person: dab.times (50, i => ({
        first_name: faker.name.firstName (),
        last_name: faker.name.lastName ()
      })
    }
  }
});

Seeding database for an specific runtime environment

NODE_ENV is used to define the runtime environmet for a NodeJS process. It is possible to seed a database connection based on the value of NODE_ENV. You do this by placing the database seed in

app/seeds/mongodb/[env]/

where env is the expected value of NODE_ENV. For example, place the seed in app/seeds/mongodb/development if you want to seed the NODE_ENV=development environment, which is the default environment if nothing is specified. Likewise, place the seed in app/seeds/mongodb/test if you want to seed the NODE_ENV=test environment.

Test-specific database seeds

It is possible to seed the database for individual unit tests. This is useful when you have data for a specific test case that does not belong in a general (global) seed. We use the beforeEach() hook and seed() method that is available on the Context in mocha.

The seed() method is added automatically to the Context by blueprint-mongodb.

Here is an example of a mocha unit test where we include a test-specific seed.

describe ('unit test', function () {
  beforeEach (async function () {
    // Apply the following seed before each test, and store it in the context
    // for the unit test

    this.models = await this.seed ({
      // this is a dab seed
    });
  });

  it ('unit test', async function () {
    // Get the models from the context. You can use destructure assignment to get
    // individual properties from the model

    const models = this.models;
  });
});