Mongoose plugin for simple addons like findOrCreate

npm install supergoose
4 downloads in the last day
110 downloads in the last week
552 downloads in the last month

supergoose Build Status

Mongoose simple plugin adding some handy functions.

Model functions

Relationship creator functions


npm install supergoose



Use mongoose's plugin method to extend your models with supergoose

var supergoose = require('supergoose')
var ClickSchema = new Schema({ ... });
ClickSchema.plugin(supergoose, [options]);
var Click = mongoose.model('Click', ClickSchema)


  • supergoose
  • options

Valid Options

  • instance
  • messages


Adds find or create functionality to mongoose models. This is handy for libraries like passport.js which require it

Click.findOrCreate({ip: ''}, function(err, doc) {});
Click.findOrCreate({ip: ''}, {browser: 'Chrome'}, function(err, click) {})


  • query
  • [doc]
  • [options]
  • callback

Valid Options

  • upsert - updates the object if it exists. Default: false


Parses the complex validation errors return from mongoose into a simple array of messages to be displayed as flash messages or something similar

var supergoose = require('supergoose')
var ClickSchema = new Schema({ip: {type: String, required: true}});
Click.plugin(supergoose, {messages: {'required': '%s is a required field'}});
var Click = mongoose.model('Click', ClickSchema);

The Click model now has an errors static method

Click.create({}, function(err, click) {
  if(err) {
    Click.errors(err, function(messages) {
      // outputs ['ip is a required field']


  • errors - error returned from mongoose command
  • callback

Relationship Creator Functions

  • parentOf / oneToMany - Creates a one to many relationship
  • childOf / manyToOne - Creates a many to one relationship
  • hasA / oneToOne - Creates a one to one relationship
  • hasMany / manyToMany - Creates a many to many relationship


  • modelName - Name of related Model
  • [myPath] - Name of path on this schema that refers to related Model. (If not provided, a default is used based on the model name. '_clicks' for the above example)


  • Relationship


When a relationship is created, it adds a path that refers to the related model on the schema that creates it. The relationship object has one property:


var supergoose = require('supergoose')
var mongoose = require('mongoose')

var ClickSchema = new Schema({ip: {type: String, required: true}, _user: {type: ObjectId}});
var UserSchema = new Schema({name: String})

UserSchema.plugin(supergoose, {instance: mongoose});
UserSchema.parentOf('Click', 'clickCollection').enforceWith('_user')


  • itsPath - Name of path on related model that refers back to this schema.
  • [options]

Valid Options

  • delete - Default: false. Only affects one to X relationships. If set to true, when a doc is removed, it will delete related docs.


MIT License

npm loves you