feat($resource): expose promise instead of only $then

- Instance or collection have `$promise` property which is the initial promise.
- Add per-action `interceptor`, which has access to entire $http response object.

BREAKING CHANGE: resource instance does not have `$then` function anymore.

Before:

Resource.query().$then(callback);

After:

Resource.query().$promise.then(callback);

BREAKING CHANGE: instance methods return the promise rather than the instance itself.

Before:

resource.$save().chaining = true;

After:

resource.$save();
resourve.chaining = true;

BREAKING CHANGE: On success, promise is resolved with the resource instance rather than http
response object.

Use interceptor to access the http response object.

Before:

Resource.query().$then(function(response) {...});

After:

var Resource = $resource('/url', {}, {
  get: {
    method: 'get',
    interceptor: {
      response: function(response) {
        // expose response
        return response;
      }
    }
  }
});

1 files changed, 161 insertions, 41 deletions

diff --git a/test/ngResource/resourceSpec.js b/test/ngResource/resourceSpec.js
index ec7f1476..6a709fb7 100644
--- a/test/ngResource/resourceSpec.js
+++ b/test/ngResource/resourceSpec.js
@@ -467,58 +467,66 @@ describe("resource", function() {
 
     describe('single resource', function() {
 
-      it('should add promise $then method to the result object', function() {
+      it('should add $promise to the result object', function() {
         $httpBackend.expect('GET', '/CreditCard/123').respond({id: 123, number: '9876'});
         var cc = CreditCard.get({id: 123});
 
-        cc.$then(callback);
+        cc.$promise.then(callback);
         expect(callback).not.toHaveBeenCalled();
 
         $httpBackend.flush();
 
-        var response = callback.mostRecentCall.args[0];
-
-        expect(response.data).toEqual({id: 123, number: '9876'});
-        expect(response.status).toEqual(200);
-        expect(response.resource).toEqualData({id: 123, number: '9876', $resolved: true});
-        expect(typeof response.resource.$save).toBe('function');
+        expect(callback).toHaveBeenCalledOnce();
+        expect(callback.mostRecentCall.args[0]).toBe(cc);
       });
 
 
-      it('should keep $then around after promise resolution', function() {
+      it('should keep $promise around after resolution', function() {
         $httpBackend.expect('GET', '/CreditCard/123').respond({id: 123, number: '9876'});
         var cc = CreditCard.get({id: 123});
 
-        cc.$then(callback);
+        cc.$promise.then(callback);
         $httpBackend.flush();
 
-        var response = callback.mostRecentCall.args[0];
-
         callback.reset();
 
-        cc.$then(callback);
+        cc.$promise.then(callback);
         $rootScope.$apply(); //flush async queue
 
-        expect(callback).toHaveBeenCalledOnceWith(response);
+        expect(callback).toHaveBeenCalledOnce();
+      });
+
+
+      it('should keep the original promise after instance action', function() {
+        $httpBackend.expect('GET', '/CreditCard/123').respond({id: 123, number: '9876'});
+        $httpBackend.expect('POST', '/CreditCard/123').respond({id: 123, number: '9876'});
+
+        var cc = CreditCard.get({id: 123});
+        var originalPromise = cc.$promise;
+
+        cc.number = '666';
+        cc.$save({id: 123});
+
+        expect(cc.$promise).toBe(originalPromise);
       });
 
 
-      it('should allow promise chaining via $then method', function() {
+      it('should allow promise chaining', function() {
         $httpBackend.expect('GET', '/CreditCard/123').respond({id: 123, number: '9876'});
         var cc = CreditCard.get({id: 123});
 
-        cc.$then(function(response) { return 'new value'; }).then(callback);
+        cc.$promise.then(function(value) { return 'new value'; }).then(callback);
         $httpBackend.flush();
 
         expect(callback).toHaveBeenCalledOnceWith('new value');
       });
 
 
-      it('should allow error callback registration via $then method', function() {
+      it('should allow $promise error callback registration', function() {
         $httpBackend.expect('GET', '/CreditCard/123').respond(404, 'resource not found');
         var cc = CreditCard.get({id: 123});
 
-        cc.$then(null, callback);
+        cc.$promise.then(null, callback);
         $httpBackend.flush();
 
         var response = callback.mostRecentCall.args[0];
@@ -534,7 +542,7 @@ describe("resource", function() {
 
         expect(cc.$resolved).toBe(false);
 
-        cc.$then(callback);
+        cc.$promise.then(callback);
         expect(cc.$resolved).toBe(false);
 
         $httpBackend.flush();
@@ -547,69 +555,125 @@ describe("resource", function() {
         $httpBackend.expect('GET', '/CreditCard/123').respond(404, 'resource not found');
         var cc = CreditCard.get({id: 123});
 
-        cc.$then(null, callback);
+        cc.$promise.then(null, callback);
         $httpBackend.flush();
         expect(callback).toHaveBeenCalledOnce();
         expect(cc.$resolved).toBe(true);
       });
+
+
+      it('should keep $resolved true in all subsequent interactions', function() {
+        $httpBackend.expect('GET', '/CreditCard/123').respond({id: 123, number: '9876'});
+        var cc = CreditCard.get({id: 123});
+        $httpBackend.flush();
+        expect(cc.$resolved).toBe(true);
+
+        $httpBackend.expect('POST', '/CreditCard/123').respond();
+        cc.$save({id: 123});
+        expect(cc.$resolved).toBe(true);
+        $httpBackend.flush();
+        expect(cc.$resolved).toBe(true);
+      });
+
+
+      it('should return promise from action method calls', function() {
+        $httpBackend.expect('GET', '/CreditCard/123').respond({id: 123, number: '9876'});
+        var cc = new CreditCard({name: 'Mojo'});
+
+        expect(cc).toEqualData({name: 'Mojo'});
+
+        cc.$get({id:123}).then(callback);
+
+        $httpBackend.flush();
+        expect(callback).toHaveBeenCalledOnce();
+        expect(cc).toEqualData({id: 123, number: '9876'});
+        callback.reset();
+
+        $httpBackend.expect('POST', '/CreditCard').respond({id: 1, number: '9'});
+
+        cc.$save().then(callback);
+
+        $httpBackend.flush();
+        expect(callback).toHaveBeenCalledOnce();
+        expect(cc).toEqualData({id: 1, number: '9'});
+      });
+
+
+      it('should allow parsing a value from headers', function() {
+        // https://github.com/angular/angular.js/pull/2607#issuecomment-17759933
+        $httpBackend.expect('POST', '/CreditCard').respond(201, '', {'Location': '/new-id'});
+
+        var parseUrlFromHeaders = function(response) {
+          var resource = response.resource;
+          resource.url = response.headers('Location');
+          return resource;
+        };
+
+        var CreditCard = $resource('/CreditCard', {}, {
+          save: {
+            method: 'post',
+            interceptor: {response: parseUrlFromHeaders}
+          }
+        });
+
+        var cc = new CreditCard({name: 'Me'});
+
+        cc.$save();
+        $httpBackend.flush();
+
+        expect(cc.url).toBe('/new-id');
+      });
     });
 
 
     describe('resource collection', function() {
 
-      it('should add promise $then method to the result object', function() {
+      it('should add $promise to the result object', function() {
         $httpBackend.expect('GET', '/CreditCard?key=value').respond([{id: 1}, {id: 2}]);
         var ccs = CreditCard.query({key: 'value'});
 
-        ccs.$then(callback);
+        ccs.$promise.then(callback);
         expect(callback).not.toHaveBeenCalled();
 
         $httpBackend.flush();
 
-        var response = callback.mostRecentCall.args[0];
-
-        expect(response.data).toEqual([{id: 1}, {id :2}]);
-        expect(response.status).toEqual(200);
-        expect(response.resource).toEqualData([ { id : 1 }, { id : 2 } ]);
-        expect(typeof response.resource[0].$save).toBe('function');
-        expect(typeof response.resource[1].$save).toBe('function');
+        expect(callback).toHaveBeenCalledOnce();
+        expect(callback.mostRecentCall.args[0]).toBe(ccs);
       });
 
 
-      it('should keep $then around after promise resolution', function() {
+      it('should keep $promise around after resolution', function() {
         $httpBackend.expect('GET', '/CreditCard?key=value').respond([{id: 1}, {id: 2}]);
         var ccs = CreditCard.query({key: 'value'});
 
-        ccs.$then(callback);
+        ccs.$promise.then(callback);
         $httpBackend.flush();
 
-        var response = callback.mostRecentCall.args[0];
-
         callback.reset();
 
-        ccs.$then(callback);
+        ccs.$promise.then(callback);
         $rootScope.$apply(); //flush async queue
 
-        expect(callback).toHaveBeenCalledOnceWith(response);
+        expect(callback).toHaveBeenCalledOnce();
       });
 
 
-      it('should allow promise chaining via $then method', function() {
+      it('should allow promise chaining', function() {
         $httpBackend.expect('GET', '/CreditCard?key=value').respond([{id: 1}, {id: 2}]);
         var ccs = CreditCard.query({key: 'value'});
 
-        ccs.$then(function(response) { return 'new value'; }).then(callback);
+        ccs.$promise.then(function(value) { return 'new value'; }).then(callback);
         $httpBackend.flush();
 
         expect(callback).toHaveBeenCalledOnceWith('new value');
       });
 
 
-      it('should allow error callback registration via $then method', function() {
+      it('should allow $promise error callback registration', function() {
         $httpBackend.expect('GET', '/CreditCard?key=value').respond(404, 'resource not found');
         var ccs = CreditCard.query({key: 'value'});
 
-        ccs.$then(null, callback);
+        ccs.$promise.then(null, callback);
         $httpBackend.flush();
 
         var response = callback.mostRecentCall.args[0];
@@ -625,7 +689,7 @@ describe("resource", function() {
 
         expect(ccs.$resolved).toBe(false);
 
-        ccs.$then(callback);
+        ccs.$promise.then(callback);
         expect(ccs.$resolved).toBe(false);
 
         $httpBackend.flush();
@@ -638,12 +702,68 @@ describe("resource", function() {
         $httpBackend.expect('GET', '/CreditCard?key=value').respond(404, 'resource not found');
         var ccs = CreditCard.query({key: 'value'});
 
-        ccs.$then(null, callback);
+        ccs.$promise.then(null, callback);
         $httpBackend.flush();
         expect(callback).toHaveBeenCalledOnce();
         expect(ccs.$resolved).toBe(true);
       });
     });
+
+    it('should allow per action response interceptor that gets full response', function() {
+      CreditCard = $resource('/CreditCard', {}, {
+        query: {
+          method: 'get',
+          isArray: true,
+          interceptor: {
+            response: function(response) {
+              return response;
+            }
+          }
+        }
+      });
+
+      $httpBackend.expect('GET', '/CreditCard').respond([{id: 1}]);
+
+      var ccs = CreditCard.query();
+
+      ccs.$promise.then(callback);
+
+      $httpBackend.flush();
+      expect(callback).toHaveBeenCalledOnce();
+
+      var response = callback.mostRecentCall.args[0];
+      expect(response.resource).toBe(ccs);
+      expect(response.status).toBe(200);
+      expect(response.config).toBeDefined();
+    });
+
+
+    it('should allow per action responseError interceptor that gets full response', function() {
+      CreditCard = $resource('/CreditCard', {}, {
+        query: {
+          method: 'get',
+          isArray: true,
+          interceptor: {
+            responseError: function(response) {
+              return response;
+            }
+          }
+        }
+      });
+
+      $httpBackend.expect('GET', '/CreditCard').respond(404);
+
+      var ccs = CreditCard.query();
+
+      ccs.$promise.then(callback);
+
+      $httpBackend.flush();
+      expect(callback).toHaveBeenCalledOnce();
+
+      var response = callback.mostRecentCall.args[0];
+      expect(response.status).toBe(404);
+      expect(response.config).toBeDefined();
+    });
   });