Added include.required to API docs, and throw errors if calling an association f…

…unction without an associated model

lib/associations/mixin.js

@@ -111,11 +111,15 @@ var Mixin = module.exports = function() {};
  * @param {boolean}         [options.hooks=false] Set to true to run before-/afterDestroy hooks when an associated model is deleted because of a cascade. For example if `User.hasOne(Profile, {onDelete: 'cascade', hooks:true})`, the before-/afterDestroy hooks for profile will be called when a user is deleted. Otherwise the profile will be deleted without invoking any hooks
  * @param {boolean}         [options.hooks=false] Set to true to run before-/afterDestroy hooks when an associated model is deleted because of a cascade. For example if `User.hasOne(Profile, {onDelete: 'cascade', hooks:true})`, the before-/afterDestroy hooks for profile will be called when a user is deleted. Otherwise the profile will be deleted without invoking any hooks
  * @param {string}          [options.as] The alias of this model. If you create multiple associations between the same tables, you should provide an alias to be able to distinguish between them. If you provide an alias when creating the assocition, you should provide the same alias when eager loading and when getting assocated models. Defaults to the singularized version of target.name
  * @param {string}          [options.as] The alias of this model. If you create multiple associations between the same tables, you should provide an alias to be able to distinguish between them. If you provide an alias when creating the assocition, you should provide the same alias when eager loading and when getting assocated models. Defaults to the singularized version of target.name
  * @param {string|object}   [options.foreignKey] The name of the foreign key in the target table or an object representing the type definition for the foreign column (see `Sequelize.define` for syntax). Defaults to the name of source + primary key of source
  * @param {string|object}   [options.foreignKey] The name of the foreign key in the target table or an object representing the type definition for the foreign column (see `Sequelize.define` for syntax). Defaults to the name of source + primary key of source
- * @param {string}          [options.onDelete='SET NULL']
+ * @param {string}          [options.onDelete='SET NULL']
  * @param {string}          [options.onUpdate='CASCADE']
  * @param {string}          [options.onUpdate='CASCADE']
  * @param {boolean}         [options.constraints=true] Should on update and on delete constraints be enabled on the foreign key.
  * @param {boolean}         [options.constraints=true] Should on update and on delete constraints be enabled on the foreign key.
  */
  */
 Mixin.hasOne = function(targetModel, options) {
 Mixin.hasOne = function(targetModel, options) {
+  if (!(targetModel instanceof this.sequelize.Model)) {
+    throw new Error(this.name + ".hasOne called with something that's not an instance of Sequelize.Model");
+  }
+
   var sourceModel = this;
   var sourceModel = this;
 
 
   // Since this is a mixin, we'll need a unique variable name for hooks (since Model will override our hooks option)
   // Since this is a mixin, we'll need a unique variable name for hooks (since Model will override our hooks option)
@@ -157,6 +161,10 @@ Mixin.hasOne = function(targetModel, options) {
  * @param {boolean}         [options.constraints=true] Should on update and on delete constraints be enabled on the foreign key.
  * @param {boolean}         [options.constraints=true] Should on update and on delete constraints be enabled on the foreign key.
  */
  */
 Mixin.belongsTo = function(targetModel, options) {
 Mixin.belongsTo = function(targetModel, options) {
+  if (!(targetModel instanceof this.sequelize.Model)) {
+    throw new Error(this.name + ".belongsTo called with something that's not an instance of Sequelize.Model");
+  }
+
   var sourceModel = this;
   var sourceModel = this;
 
 
   // Since this is a mixin, we'll need a unique variable name for hooks (since Model will override our hooks option)
   // Since this is a mixin, we'll need a unique variable name for hooks (since Model will override our hooks option)
@@ -244,6 +252,10 @@ Mixin.belongsTo = function(targetModel, options) {
  * @param {boolean}           [options.constraints=true] Should on update and on delete constraints be enabled on the foreign key.
  * @param {boolean}           [options.constraints=true] Should on update and on delete constraints be enabled on the foreign key.
  */
  */
 Mixin.hasMany = function(targetModel, options) {
 Mixin.hasMany = function(targetModel, options) {
+  if (!(targetModel instanceof this.sequelize.Model)) {
+    throw new Error(this.name + ".hasMany called with something that's not an instance of Sequelize.Model");
+  }
+
   var sourceModel = this;
   var sourceModel = this;
 
 
   // Since this is a mixin, we'll need a unique variable name for hooks (since Model will override our hooks option)
   // Since this is a mixin, we'll need a unique variable name for hooks (since Model will override our hooks option)

lib/model.js

@@ -640,7 +640,13 @@ module.exports = (function() {
    * @param  {Object}                    [options] A hash of options to describe the scope of the search
    * @param  {Object}                    [options] A hash of options to describe the scope of the search
    * @param  {Object}                    [options.where] A hash of attributes to describe your search. See above for examples.
    * @param  {Object}                    [options.where] A hash of attributes to describe your search. See above for examples.
    * @param  {Array<String>}             [options.attributes] A list of the attributes that you want to select
    * @param  {Array<String>}             [options.attributes] A list of the attributes that you want to select
-   * @param  {Array<Object|Model>}       [options.include] A list of associations to eagerly load. Supported is either { include: [ Model1, Model2, ...] } or { include: [ { model: Model1, as: 'Alias' } ] }. If your association are set up with an `as` (eg. `X.hasMany(Y, { as: 'Z }`, you need to specify Z in the as attribute when eager loading Y). When using the object form, you can also specify `attributes` to specify what columns to load, `where` to limit the relations, and `include` to load further nested relations
+   * @param  {Array<Object|Model>}       [options.include] A list of associations to eagerly load using a left join. Supported is either `{ include: [ Model1, Model2, ...]}` or `{ include: [{ model: Model1, as: 'Alias' }]}`. If your association are set up with an `as` (eg. `X.hasMany(Y, { as: 'Z }`, you need to specify Z in the as attribute when eager loading Y).
+   * @param  {Model}                     [optinos.include[].model] The model you want to eagerly load
+   * @param  {String}                    [options.include[].as] The alias of the relation, in case the model you want to eagerly load is aliassed.
+   * @param  {Object}                    [options.include[].where] Where clauses to apply to the child models. Note that this converts the eager load to an inner join, unless you explicitly set `required: true`
+   * @param  {Array<String>}             [options.include[].attributes] A list of attributes to select from the child model
+   * @param  {Boolean}                   [options.include[].required] If true, converts to an inner join, which means that the parent model will only be loaded if it has any matching children. True if `include.where` is set, false otherwise.
+   * @param  {Array<Object|Model>}       [options.include[].include] Load further nested related models
    * @param  {String|Array|Sequelize.fn} [options.order] Specifies an ordering. If a string is provided, it will be esacped. Using an array, you can provide several columns / functions to order by. Each element can be further wrapped in a two-element array. The first element is the column / function to order by, the second is the direction. For example: `order: [['name', 'DESC']]`. In this way the column will be escaped, but the direction will not.
    * @param  {String|Array|Sequelize.fn} [options.order] Specifies an ordering. If a string is provided, it will be esacped. Using an array, you can provide several columns / functions to order by. Each element can be further wrapped in a two-element array. The first element is the column / function to order by, the second is the direction. For example: `order: [['name', 'DESC']]`. In this way the column will be escaped, but the direction will not.
    * @param  {Number}                    [options.limit]
    * @param  {Number}                    [options.limit]
    * @param  {Number}                    [options.offset]
    * @param  {Number}                    [options.offset]

lib/sequelize.js

@@ -197,7 +197,7 @@ module.exports = (function() {
    */
    */
   Sequelize.prototype.Validator = Sequelize.Validator = require('validator');
   Sequelize.prototype.Validator = Sequelize.Validator = require('validator');
 
 
-  Sequelize.Model = Sequelize.Model = Model;
+  Sequelize.prototype.Model = Sequelize.Model = Model;
 
 
   for (var dataType in DataTypes) {
   for (var dataType in DataTypes) {
     Sequelize[dataType] = DataTypes[dataType];
     Sequelize[dataType] = DataTypes[dataType];