Always lookup relation object on model instance.

All methods and properties that are added by a relation are now
required to look up the relation object when they're invoked.
Previously, the relation object used to define the method was assumed
to be constant, but the lookup allows the relation object to be
overridden & redefine aspects of the relation object.

This is required for supporting relations in azul-transaction.

lib/relations/base.js

@@ -315,8 +315,8 @@ BaseRelation.reopen(/** @lends BaseRelation# */ {
 
   /**
    * @function BaseRelation~MethodCallable
-   * @param {BaseRelation} relation [description]
-   * @return {Object|Function} A value that should be added
+   * @param {String} relationKey Key to find the relation on the instance.
+   * @return {Object|Function} A value that should be added.
    */
 
   /**
@@ -341,13 +341,15 @@ BaseRelation.reopen(/** @lends BaseRelation# */ {
    *
    *     CustomRelation.reopenClass({
    *       methods: {
-   *         'get<Singular>': function(relation) {
+   *         'get<Singular>': function(relationKey) {
    *           return function() {
+   *             var relation = this[relationKey];
    *             return this['_' + relation._name];
    *           };
    *         },
-   *         'set<Singular>': function(relation) {
+   *         'set<Singular>': function(relationKey) {
    *           return function(value) {
+   *             var relation = this[relationKey];
    *             this['_' + relation._name] = value;
    *           };
    *         }
@@ -378,15 +380,23 @@ BaseRelation.reopen(/** @lends BaseRelation# */ {
    * @return {Object} A set of attributes.
    */
   methods: function(existing) {
+    // all relations define a `<name>Relation` method that is used to
+    // access the relation from model instances & also to dispatch individual
+    // method calls. this simply returns the relation object (though it can be
+    // overridden by subclasses or individual instances).
     var self = this;
+    var relationKey = this._name + 'Relation';
+    var base = _.object([
+      [relationKey, property(function() { return self; })]
+    ]);
     var methods = this.__identity__.methods;
     return _.transform(methods, function(result, method, key) {
       var name = self.template(key);
       var include = !method.optional || !existing[name];
       if (include) {
-        result[name] = method(self);
+        result[name] = method(relationKey);
       }
-    }, {});
+    }, base);
   }
 
 });
@@ -420,12 +430,12 @@ BaseRelation.reopenClass(/** @lends BaseRelation */ {
    * @return {BaseRelation~MethodCallable}
    */
   property: function(getterName, setterName) {
-    return function(relation) {
+    return function(relationKey) {
       var getter = getterName && function() {
-        return relation[getterName](this);
+        return this[relationKey][getterName](this);
       };
       var setter = setterName && function(value) {
-        return relation[setterName](this, value);
+        return this[relationKey][setterName](this, value);
       };
       return property(getter, setter);
     };
@@ -450,6 +460,11 @@ BaseRelation.reopenClass(/** @lends BaseRelation */ {
    * model instance on which the method is operating, and the remaining
    * arguments will be any that were passed to the method.
    *
+   * The resulting method looks up the relationship currently defined on the
+   * instance rather than assuming that it has remained unchanged since the
+   * method was added to the model class. This allows overriding of the
+   * relation object (used by azul-transaction).
+   *
    * The example given in {@link BaseRelation#methods} could be re-implemented
    * using this helper as follows:
    *
@@ -475,14 +490,15 @@ BaseRelation.reopenClass(/** @lends BaseRelation */ {
    * @return {BaseRelation~MethodCallable}
    */
   method: function(name) {
-    return function(relation) {
+    return function(relationKey) {
       return function() {
+        var relation = this[relationKey];
         var fn = relation[name];
         var args = _.toArray(arguments);
         return fn.apply(relation, [this].concat(args));
       };
     };
-  }
+  },
 
 });
 

lib/relations/belongs_to.js

@@ -96,30 +96,6 @@ var invalidatesQuery = function(fn) {
 
 BelongsTo.reopen(/** @lends BelongsTo# */ {
 
-  /**
-   * The identity property for this relation.
-   *
-   * This property allows access to the underlying relation object, allowing
-   * you to access details about how the relation was created/configured. This
-   * method is currently only intended for internal use, but if you have a
-   * reason for it to be documented publicly, please create an issue on GitHub
-   * and let us know.
-   *
-   * It is accessible on an individual model via `<singular>Relation`. For
-   * instance, an article that belongs to an author would cause this method to
-   * get triggered via `article.authorRelation`.
-   *
-   * The naming conventions are set forth in {@link BelongsTo.methods}.
-   *
-   * @method
-   * @protected
-   * @param {Model} instance The model instance on which to operate.
-   * @see {@link BaseRelation#methods}
-   */
-  identity: function(/*instance*/) {
-    return this;
-  },
-
   /**
    * The item property for this relation.
    *
@@ -357,12 +333,11 @@ BelongsTo.reopenClass(/** @lends BelongsTo */ {
    */
   methods: {
     '<singular>': BaseRelation.property('item', 'set'),
-    '<singular>Relation': BaseRelation.property('identity'),
     'get<Singular>': BaseRelation.method('item'),
     'set<Singular>': BaseRelation.method('set'),
     'create<Singular>': BaseRelation.method('create'),
     'fetch<Singular>': BaseRelation.method('fetch'),
-    '<foreignKey>': _.extend(function(/*relation*/) {
+    '<foreignKey>': _.extend(function(/*relationKey*/) {
       return attr(undefined, { writable: false });
     }, { optional: true }),
     'save': BaseRelation.method('save')

lib/relations/has_many.js

@@ -84,30 +84,6 @@ var notify = function(name) {
 
 HasMany.reopen(/** @lends HasMany# */ {
 
-  /**
-   * The identity property for this relation.
-   *
-   * This property allows access to the underlying relation object, allowing
-   * you to access details about how the relation was created/configured. This
-   * method is currently only intended for internal use, but if you have a
-   * reason for it to be documented publicly, please create an issue on GitHub
-   * and let us know.
-   *
-   * It is accessible on an individual model via `<plural>Relation`. For
-   * instance, a user that has many articles would cause this method to get
-   * triggered via `user.articlesRelation`.
-   *
-   * The naming conventions are set forth in {@link HasMany.methods}.
-   *
-   * @method
-   * @protected
-   * @param {Model} instance The model instance on which to operate.
-   * @see {@link BaseRelation#methods}
-   */
-  identity: function(/*instance*/) {
-    return this;
-  },
-
   /**
    * Determine if this relation is a many-to-many relationship, that is if the
    * inverse relationship is a many relationship as well. Has many
@@ -419,7 +395,6 @@ HasMany.reopenClass(/** @lends HasMany */ {
    */
   methods: {
     '<plural>': BaseRelation.property('collection'),
-    '<plural>Relation': BaseRelation.property('identity'),
     '<singular>Objects': BaseRelation.property('objectsQuery'),
     'create<Singular>': BaseRelation.method('createObject'),
     'add<Singular>': BaseRelation.method('addObjects'),

test/relations/base_tests.js

@@ -1,11 +1,13 @@
 'use strict';
 
 var chai = require('chai');
+var sinon = require('sinon'); chai.use(require('sinon-chai'));
 var expect = chai.expect;
 
 var Database = require('../../lib/database');
 var FakeAdapter = require('../fakes/adapter');
 var BaseRelation = require('../../lib/relations/base');
+var property = require('../../lib/util/property').fn;
 
 require('../helpers/model');
 
@@ -57,4 +59,55 @@ describe('BaseRelation', function() {
     }).to.throw(/associatePrefetchResults.*must.*implemented.*subclass/i);
   });
 
+  it('dispatches methods & properties to instance relation', function() {
+    var method = sinon.spy();
+    var getter = sinon.spy();
+    var setter = sinon.spy();
+
+    var Relation = BaseRelation.extend({
+      method: method,
+      get: getter,
+      set: setter
+    });
+    Relation.reopenClass({
+      methods: {
+        '<singular>Method': BaseRelation.method('method'),
+        '<singular>Property': BaseRelation.property('get', 'set'),
+      }
+    });
+
+    // this is a strategy that azul-transaction uses, so we need to support it
+    var Base = db.Model.extend({ custom: Relation.attr()() });
+    var relation = Object.create(Base.__class__.prototype.customRelation);
+    var Override = Base.extend({
+      customRelation: property(function() { return relation; })
+    });
+
+    var base = Base.create();
+    var override = Override.create();
+
+    base.customMethod();
+    override.customMethod(); // should be called with custom object
+    base.customProperty;
+    override.customProperty; // should be called with custom object
+    base.customProperty = undefined;
+    override.customProperty = undefined; // should be called with custom object
+
+    expect(method.getCall(0).thisValue)
+      .to.equal(Base.__class__.prototype.customRelation);
+    expect(method.getCall(1).thisValue)
+      .to.equal(relation);
+    expect(method).to.have.been.calledTwice;
+    expect(getter.getCall(0).thisValue)
+      .to.equal(Base.__class__.prototype.customRelation);
+    expect(getter.getCall(1).thisValue)
+      .to.equal(relation);
+    expect(getter).to.have.been.calledTwice;
+    expect(setter.getCall(0).thisValue)
+      .to.equal(Base.__class__.prototype.customRelation);
+    expect(setter.getCall(1).thisValue)
+      .to.equal(relation);
+    expect(setter).to.have.been.calledTwice;
+  });
+
 });