@farmo/farmo-orm

Farmo Orm

An override for the orm hook in Sails. Loads and instantiates your model files as Mongoose models instead of Waterline models.

Installation

From your Sails app:

Please note that this might not work and will be moved to a private NPM package in the future

npm i git+https://github.com/Farmo-Technologies/farmo-orm.git

That's it!.... almost. For the time being, you also need to disable the ORM hook. To do so, merge the following into your .sailsrc file:

{
  "hooks": {
    "orm": false,
    "pubsub": false,
    "blueprints": false
  }
}

Compatibility

Needs...

The following core hooks must be enabled, in order for this hook to work properly:

• moduleloader (enabled by default)
• userconfig (enabled by default)

Must disable...

In order to use this hook, you must disable the following core hooks in your Sails app:

• blueprints
• pubsub

Usage

Defining models

This hook loads model definitions according to standard Sails conventions, relying on the core moduleloader hook (i.e. usually from api/models/*.js). The model definition must export a dictionary. If a schema property is specified, it must also be a dictionary, and it will be passed in as an argument to Mongoose's Schema constructor. For example, to build a Sails model equivalent to this example from the Mongoose docs:

/**
 * Blog (model)
 *
 * Usage:
 * • `Blog`  _(global)_
 * • `sails.models.blog`
 *
 * @definition
 *   @source `api/models/Blog.js`
 *   @type {Dictionary}
 */
module.exports = {

  schema: {
    title:  String,
    author: String,
    body:   String,
    comments: [{ body: String, date: Date }],
    date: { type: Date, default: Date.now },
    hidden: Boolean,
    meta: {
      votes: Number,
      favs:  Number
    }
  },

};

Once the hook "new"s up the schema you provided into a Schema instance, that Schema instance is then used to create a Model (using mongoose.model(...)). Refer to the Mongoose docs for available model methods such as .find() and .create(). If any of the terminology in this README sounds unfamiliar, you should give the Mongoose "Getting Started" guide a thorough read before proceeding.

Customizing a Schema

If you need to customize how the Schema or Model instance is built, you may pass in a constructSchema and/or a constructModel interceptor function as part of your model definition.

Let's return to our Blog model for an example:

/**
 * Example Mongoose model.
 */
const { Schema } = require('mongoose');
module.exports = {
  // Specify the datastore connection. if connection key is not set it will use default.
  connection: 'local',
  schema: {
    _id: {
      type: String,
      required: true,
      immutable: true
    },
   
    geo: {
      type: {
        type: String,
        enum: ['Polygon', 'Point', 'LineString'],
  
      },
      coordinates: {
        type: Schema.Types.Mixed,
        required: true
      },
  
    },
    field: {
      type: String,
      required: true,
      // If a reference is between databases ref needs to be a function like this.
      ref: () => Field
    },
    user: {
      type: String,
      required: true,
      immutable: true
    },
    team: {
      type: String,
      required: true,
      immutable: true
    },
    created_at: {
      type: Date,
      required: true,
      immutable: true,
      default: new Date()
    },
    updated_at: {
      type: Date,
      required: true,
      default: new Date()
    },
  },
  /**
   * Optional: Specify indexes
   * See Docs for more info: https://mongoosejs.com/docs/guide.html#indexes
   */
  indexes: { 
    
    geo: '2dsphere' 
  },
  /**
   * Optional: Specify queries.
   * See Docs for more info: https://mongoosejs.com/docs/guide.html#query-helpers
   */
  queries: {
    byTeam: (team) => {
      return this.where({ team });
    }
  },
  /**
   * Optional: Specify statics.
   * See docs for more info: https://mongoosejs.com/docs/guide.html#statics
   */
  statics: {
    findByUser: (user) => {
      return this.where({ user });
    }
  }


  /**
   * constructSchema()
   *
   * Note that this function must be synchronous!
   * Also Note. Most of this function can be done with the above keys.
   * 
   * @param  {Dictionary} schemaDefinedAbove  [the raw schema defined above, or `{}` if no schema was provided]
   * @param  {SailsApp} sails                 [just in case you have globals disabled, this way you always have access to `sails`]
   * @return {MongooseSchema}
   */
  constructSchema: function (schemaDefinedAbove, sails) {
    // e.g. we might want to pass in a second argument to the schema constructor
    var newSchema = new sails.mongoose.Schema(schemaDefinedAbove, { autoIndex: false });

    // Or we might want to define an instance method:
    newSchema.method('meow', function () {
      console.log('meeeeeoooooooooooow');
    });

    // Or a static ("class") method:
    newSchema.static('findByName', function (name, callback) {
      return this.find({ name: name }, callback);
    });

    // Regardless, you must return the instantiated Schema instance.
    return newSchema;
  }

};

As you can see, this allows you to make many exciting customizations to your models. More on that in the Mongoose docs about "schemas".

Connecting

When this hook loads, it automatically connects to the configured Mongo URI (see the Configuration section below). All of your models share this Mongo URI by default.

Configuration

This hook uses the following properties on sails.config:

Property	Type	Default	Details
sails.config.datastores.default.uri	((string))	'mongodb://localhost/my_sails_app'	The Mongo connection URI to use when communicating with the Mongo database for any of this app's models.
sails.config.datastores.default.connectionOpts	((dictionary))	{}	This optional configuration is a dictionary of additional options to pass in to mongoose when .connect() is called. See http://mongoosejs.com/docs/connections.html for a full list of available options.
sails.config.globals.models	((boolean))	true	Whether or not to expose each of your app's models as global variables (using their globalId). If this setting is disabled, you can still access your models via sails.models.*. E.g. a model defined in api/models/User.js would have a globalId of User by default.