mongogo

Shorthand schema declaration for Mongoose

Usage no npm install needed!

<script type="module">
  import mongogo from 'https://cdn.skypack.dev/mongogo';
</script>

README

Mongogo

MIT licensed npm Coveralls branch Build Status Twitter

Mongogo is a small library that simplifies common schema declarations for Mongoose. It has been designed for simplicity and minimalism; its only dependency is Mongoose^4.

Usage

The aim of Mongogo is to provide a number of shorthand schema declaration methods that facilitate faster coding and more readable syntax.

With mongogo.Schema and mongogo.Model, when you specify your top-level fields as strings, it will convert them from Mongogo shorthand to their equivalent Mongoose JSON. Three additional methods, mongogo.field(), mongogo.option(), mongogo.index() are provided for using Mongogo shorthand in nested objects or other areas.

Example

Regular Mongoose:

let mongoose = require('mongoose');

let schema = mongoose.Schema({
  username:       { type: String, unique: true },
  email:          { type: String, unique: true },
  first_name:     { type: String, trim: true },
  last_name:      { type: String, trim: true },
  age:            { type: number, min: 18, max: 100 },
  dob:            { type: Date, default: new Date(123467) },
  created:        { type: Date, default: Date.now },
  alive:          { type: Boolean, default: true },
  best_friend:    { type: mongoose.Schema.Types.ObjectId, ref: 'person' },
  favorite_thing: { type: mongoose.Schema.Type.ObjectId },
  parents: {
    father:       { type: mongoose.Schema.Types.ObjectId, ref: 'person' },
    mother:       { type: mongoose.Schema.Types.ObjectId, ref: 'person' },
  },
  some_string:    String,
  job_title:      { type: String, index: true, sparse: true }
}, {
  timestamps: true,
  autoIndex: false,
  strict:   'throw'
});

schema.index({ username: 1, email: 1, dob: -1 }, { unique: true });
schema.index({ best_friend: 1, job_title: -1 }, { sparse: true });

schema.pre('find', ...);

module.exports = mongoose.model('person', schema);

Mongogo:

import { mongogo, field, index } from 'mongogo';

let schema = mongogo.Schema({
  username:         'string,unique',
  email:            'string,unique',
  first_name:       'string,trim',
  last_name:        'string,trim',
  age:              'number,min:18,max:100',
  dob:              'date,default:1234567',
  created:          'now', // or the long way, 'date,default:now'
  alive:            'boolean,default:true',
  best_friend:      'ref:person,sparse',

  favorite_thing:    'id',
  parents: {
    father:     field('ref:person,index'),
    mother:     field('ref:person,index')
  },

  // Any non-string field value is passed to Mongoose as-is.
  some_string:  String,
  job_title:    { type: String, index: true, sparse: true }
},
  'timestamps,ai:false,throw'      // Options
);

// Index shorthand
schema.index([
  'username,+email,-dob,$unique',
  'best_friend,-job_title,$sparse'
]);

schema.pre('find', ...);

export default mongogo.mongoose.model('person', schema);

Mongogo Shorthand Model Syntax:


import { mongogo, field } from 'mongogo';

mongogo.Model('MyModel', {
  fields: {
    username:           'string,unique',
    email:              'string,unique',
    first_name:         'string,trim',
    last_name:          'string,trim',
    age:                'number,min:18,max:100',
    dob:                'date,default:1234567',
    created:            'now',
    alive:              'boolean,default:yes',
    best_friend:        'ref:person,sparse',

    favorite_thing:     'id',  
    parents: {
      father:           field('ref:person,index'),
      mother:           field('ref:person,index')
    },

    some_string:        String,
    job_title:          { type: String, index: true, sparse: true }
  },

  options: 'timestamps,ai:false,throw',

  index: [
    'username,+email,-dob,$unique', // shorthand
    { fields: { best_friend: 1, job_title: -1 }, options: { sparse: true }} // JSON declaration, if needed  
  ],

  statics: {
    findByUsername: function(username){
      return this.findOne({ username: username }).exec();
    }
  },

  methods: {
    isAlive: function(){
      return this.alive === true;
    },
    cakeDay: function(){
      this.age++;
    }
  },

  schema: function(schema){
    schema.pre('find', ...)
  }

  connection: myMongoConnection // Optional - for use when you want to use your own connection, or `false` to return the generated schema without compiling model.
});

Keywords

Mongogo's field and option keywords are available on the wiki, and in keywords.js.

Variable / Default Values

Mongogo converts default and variable values to the correct type for the following types:

  • String (simple strings only - read more below)
  • Boolean
  • Number
  • Date ('now' for Date.now or a number to use as a UNIX timestamp)

The other types (Buffer, Array, Mixed, ObjectId / id) cannot have default values specified. Mongogo is for shorthand, so in the event that you need to define these types, you should use regular Mongoose syntax instead.

Strings

The shorthand parser is very simple - if you need to specify string values, they too should be simple. You can use the extras parameter to specify more complex values.

Examples:

field('default:monday');
option('read:document');
field(`string,default:I am a string!,trim`);
field('string,trim', { default: "I, am, Silliam, Whattner!"});

Exports

The mongogo object exports the following:


import {
  default,      // Self-reference, for `import mongogo from 'mongogo';`
  mongogo,      // Self-reference, for import statements
  mongoose,     // Reference to require('mongoose')

  // Methods
  Schema,       // Schema method
  Model,        // Model method
  field,        // field method
  option,       // option method

  // Keywords
  fields,       // field keywords used by `field`
  keywords,     // semver compatibility - references `fields`
  options,      // options keywords used by `options`

  // Convenience
  ObjectId,     // Reference to mongoose ObjectId
  Mixed,        // Reference to mongoose Mixed


} from 'mongogo';

More Documentation on the Wiki

Complete documentation can be found on the Wiki.

License

Mongogo is licensed under the MIT License. (Readable in LICENSE) It's completely free to use for both personal and commercial purposes. Enjoy!