feat(lib): add related method on Resource

The `#related` method allows navigation using embedded or links.

This enables consumers to not care in which section the HAL the link is
placed. It looks in embedded first, and if the rel is not found there
it then looks in links. Templated links are expanded using the
optional `params` argument.

lib/hyperagent/resource.js

@@ -109,6 +109,22 @@ Resource.prototype.link = function link(rel, params) {
   return _link;
 };
 
+/**
+ * Returns the set of resource(s) identified by the given `rel`
+ * (expanding the link template if params are provided).
+ *
+ * Arguments:
+ *  - rel: The rel of the link.
+ *  - params: Optional parameters to expand the link if it is a templated link.
+ */
+Resource.prototype.related = function related(rel, params) {
+  if (params || !this.embedded.hasOwnProperty(rel)) {
+    return this.link(rel, params);
+  } else {
+    return this.embedded[rel];
+  } 
+};
+
 /**
  * Parses a response string.
  */

test/spec/test-resource.js

@@ -285,6 +285,53 @@
       });
     });
 
+    describe('#related', function () {
+      beforeEach(function () {
+        this.agent = new Hyperagent.Resource({ url: 'http://example.com/' });
+        this.ajaxCalls = [];
+        Hyperagent.configure('ajax', function () {
+          this.ajaxCalls.push(arguments);
+        }.bind(this));
+      });
+
+      it('should follow links when there is no embedded', function () {
+        this.agent._load({ _links: {
+          user: { href: 'http://example.com/users/passy' }
+        } });
+        var link = this.agent.related('user');
+        assert.equal(link.url(), 'http://example.com/users/passy');
+      });
+
+      it('should expand templates', function () {
+        this.agent._load({ _links: {
+          user: { href: 'http://example.com/users/{user}', templated: true }
+        } });
+        var link = this.agent.related('user', { user: 'passy' });
+        assert.equal(link.url(), 'http://example.com/users/passy');
+      });
+
+      it('should return cached resource from embedded when available', function () {
+        this.agent._load({ _embedded: {
+          user: { _links: { self: { href: 'http://example.com/users/passy' }}}
+        } });
+        var link = this.agent.related('user');
+        assert.equal(link.url(), 'http://example.com/users/passy');
+      });
+
+      it('should prefer embedded over links', function () {
+        this.agent._load({
+          _embedded: {
+            user: { _links: { self: { href: 'http://example.com/users/passy' }}}
+          },
+          _links: {
+            user: { href: 'http://example.com/users/fail' }
+          } });
+        var link = this.agent.related('user');
+        assert.equal(link.url(), 'http://example.com/users/passy');
+      });
+
+    });
+
     describe('loadHooks', function () {
       afterEach(function () {
         Hyperagent.configure('loadHooks', []);