refactor(belongs-to-many): initial work on belongsToMany as a replacement to 2x hasMany

lib/associations/has-many.js

@@ -6,7 +6,13 @@ var Utils = require('./../utils')
   , Association = require('./base')
   , Transaction = require('../transaction')
   , Model = require('../model')
-  , CounterCache = require('../plugins/counter-cache');
+  , CounterCache = require('../plugins/counter-cache')
+  , deprecatedSeen = {}
+  , deprecated = function(message) {
+    if (deprecatedSeen[message]) return;
+    console.warn(message);
+    deprecatedSeen[message] = true;
+  };
 
 var HasManySingleLinked = require('./has-many-single-linked')
   , HasManyDoubleLinked = require('./has-many-double-linked');
@@ -203,6 +209,8 @@ module.exports = (function() {
     // is there already a single sided association between the source and the target?
     // or is the association on the model itself?
     if ((this.isSelfAssociation && Object(this.through.model) === this.through.model) || doubleLinked) {
+      deprecated('Using 2 x hasMany to represent N:M relations has been deprecated. Please use belongsToMany instead');
+
       // We need to remove the keys that 1:M have added
       if (this.isSelfAssociation && doubleLinked) {
         if (self.through.model.rawAttributes[this.targetAssociation.identifier]

lib/associations/mixin.js

@@ -3,6 +3,7 @@
 var Utils = require('./../utils')
   , HasOne = require('./has-one')
   , HasMany = require('./has-many')
+  , BelongsToMany = require('./belongs-to-many')
   , BelongsTo = require('./belongs-to');
 
 /**
@@ -266,6 +267,100 @@ Mixin.hasMany = function(targetModel, options) {
   return association;
 };
 
+/**
+ * Create an N:M association with a join table
+ *
+ * ```js
+ * User.belongsToMany(Project)
+ * Project.belongsToMany(User)
+ * ```
+ * By default, the name of the join table will be source+target, so in this case projectsusers. This can be overridden by providing either a string or a Model as `through` in the options.
+
+ * The following methods are injected on the source:
+ *
+ * * get[AS] - for example getPictures(finder). The finder object is passed to `target.find`.
+ * * set[AS] - for example setPictures(instances, defaultAttributes|options). Update the associations. All currently associated models that are not in instances will be removed.
+ * * add[AS] - for example addPicture(instance, defaultAttributes|options). Add another associated object.
+ * * add[AS] [plural] - for example addPictures([instance1, instance2], defaultAttributes|options). Add some more associated objects.
+ * * create[AS] - for example createPicture(values, options). Build and save a new association.
+ * * remove[AS] - for example removePicture(instance). Remove a single association.
+ * * remove[AS] [plural] - for example removePictures(instance). Remove multiple association.
+ * * has[AS] - for example hasPicture(instance). Is source associated to this target?
+ * * has[AS] [plural] - for example hasPictures(instances). Is source associated to all these targets?
+ *
+ * All methods return a promise
+ *
+ * If you use a through model with custom attributes, these attributes can be set when adding / setting new associations in two ways. Consider users and projects from before
+ * with a join table that stores whether the project has been started yet:
+ * ```js
+ * var UserProjects = sequelize.define('userprojects', {
+ *   started: Sequelize.BOOLEAN
+ * })
+ * User.belongsToMany(Project, { through: UserProjects })
+ * Project.belongsToMany(User, { through: UserProjects })
+ * ```
+ * ```js
+ * jan.addProject(homework, { started: false }) // The homework project is not started yet
+ * jan.setProjects([makedinner, doshopping], { started: true}) // Both shopping and dinner has been started
+ * ```
+ *
+ * If you want to set several target instances, but with different attributes you have to set the attributes on the instance, using a property with the name of the through model:
+ *
+ * ```js
+ * p1.userprojects {
+ *   started: true
+ * }
+ * user.setProjects([p1, p2], {started: false}) // The default value is false, but p1 overrides that.
+ * ```
+ *
+ * Similarily, when fetching through a join table with custom attributes, these attributes will be available as an object with the name of the through model.
+ * ```js
+ * user.getProjects().then(function (projects) {
+ *   var p1 = projects[0]
+ *   p1.userprojects.started // Is this project started yet?
+ * })
+ * ```
+ *
+ * @param {Model}               target
+ * @param {object}              [options]
+ * @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 {Model|string|object} [options.through] The name of the table that is used to join source and target in n:m associations. Can also be a sequelize model if you want to define the junction table yourself and add extra attributes to it.
+ * @param {Model}               [options.through.model] The model used to join both sides of the N:M association.
+ * @param {object}              [options.through.scope] A key/value set that will be used for association create and find defaults on the through model. (Remember to add the attributes to the through model)
+ * @param {boolean}             [options.through.unique=true] If true a unique key will be generated from the foreign keys used (might want to turn this off and create specific unique keys when using scopes)
+ * @param {string|object}       [options.as] The alias of this association. If you provide a string, it should be plural, and will be singularized using node.inflection. If you want to control the singular version yourself, provide an object with `plural` and `singular` keys. See also the `name` option passed to `sequelize.define`. 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 pluralized name of target
+ * @param {string|object}       [options.foreignKey] The name of the foreign key in the join table (representing the source model) or an object representing the type definition for the foreign column (see `Sequelize.define` for syntax). When using an object, you can add a `name` property to set the name of the colum. Defaults to the name of source + primary key of source
+ * @param {string|object}       [options.otherKey] The name of the foreign key in the join table (representing the target model) or an object representing the type definition for the other column (see `Sequelize.define` for syntax). When using an object, you can add a `name` property to set the name of the colum. Defaults to the name of target + primary key of target
+ * @param {object}              [options.scope] A key/value set that will be used for association create and find defaults on the target. (sqlite not supported for N:M)
+ * @param {string}              [options.onDelete='SET NULL|CASCADE'] Cascade if this is a n:m, and set null if it is a 1:m
+ * @param {string}              [options.onUpdate='CASCADE']
+ * @param {boolean}             [options.constraints=true] Should on update and on delete constraints be enabled on the foreign key.
+ */
+Mixin.belongsToMany = function(targetModel, options) {
+  if (!(targetModel instanceof this.sequelize.Model)) {
+    throw new Error(this.name + ".belongsToMany called with something that's not an instance of Sequelize.Model");
+  }
+
+  var sourceModel = this;
+
+  // Since this is a mixin, we'll need a unique variable name for hooks (since Model will override our hooks option)
+  options = options || {};
+  options.hooks = options.hooks === undefined ? false : Boolean(options.hooks);
+  options.useHooks = options.hooks;
+
+  options = Utils._.extend(options, Utils._.omit(sourceModel.options, ['hooks']));
+
+  // the id is in the foreign table or in a connecting table
+  var association = new BelongsToMany(sourceModel, targetModel, options);
+  sourceModel.associations[association.associationAccessor] = association.injectAttributes();
+
+  association.injectGetter(sourceModel.Instance.prototype);
+  association.injectSetter(sourceModel.Instance.prototype);
+  association.injectCreator(sourceModel.Instance.prototype);
+
+  return association;
+};
+
 Mixin.getAssociation = function(target, alias) {
   for (var associationName in this.associations) {
     if (this.associations.hasOwnProperty(associationName)) {