Mongoose plugin for simple addons like findOrCreate


Mongoose simple plugin adding some handy 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 - The supergoose function
  • options - Options object

Valid Options

  • instance - The instance of mongoose used in the application (Required for Schema functions)
  • messages - Object of custom messages (Required for errors function)

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

Click.findOrCreate({ip: ''}, function(errdoc) {});
Click.findOrCreate({ip: ''}, {browser: 'Chrome'}, function(errclick) {})


  • query - Conditions with which to search for document
  • [doc] - Document to insert if document not found
  • [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(errclick) {
  if(err) {
    Click.errors(err, function(messages) {
      // outputs ['ip is a required field'] 


  • errors - error returned from mongoose command
  • callback

  • 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