README.md

supergoose

Mongoose simple plugin adding some handy functions.

Model functions

• findOrCreate
• errors

Relationship creator functions

• parentOf/oneToMany
• childOf/manyToOne
• hasA/oneToOne
• hasMany/manyToMany
• Relationship

Installation

npm install supergoose

Usage

Initialization

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)

Arguments

• 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)

    ---

    ### findOrCreate()

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

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

    Arguments

    • 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

    ---

    ### errors

    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) {
          console.log(messages);
          // outputs ['ip is a required field']
        })
      }
    });

    Arguments

    • 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

    Arguments

    • 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)

    Returns

    • Relationship

    ---

    ### 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:

    enforceWith

    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')

    Arguments

    • 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.

      License

      MIT License