feat($resource): add support for wrapped responses

docs/content/error/resource/badresourceloc.ngdoc

@@ -0,0 +1,7 @@
+@ngdoc error
+@name $resource:badresourceloc
+@fullName responseData is not a function or string
+@description
+
+This error occurs when a {@link api/ngResource.$resource `$resource`} service action's responseData field
+is not a string or a function.

src/ngResource/resource.js

@@ -141,6 +141,9 @@ function shallowClearAndCopy(src, dst) {
  *   - **`interceptor`** - `{Object=}` - The interceptor object has two optional methods -
  *     `response` and `responseError`. Both `response` and `responseError` interceptors get called
  *     with `http response` object. See {@link ng.$http $http interceptors}.
+ *   - **`resourceData`** - `{string=|function(data)=}` - A string specifying which field in the
+ *      response should be converted to a Resource object or a function which is passed the
+ *      data from the request and should return the object to be converted to a Resource object.
  *
  * @returns {Object} A resource "class" object with methods for the default set of resource actions
  *   optionally extended with custom `actions`. The default set contains these actions:
@@ -512,6 +515,20 @@ angular.module('ngResource', ['ng']).
             var data = response.data,
                 promise = value.$promise;
 
+            if(action.resourceData) {
+                if(isFunction(action.resourceData)) {
+                    data = action.resourceData(response.data);
+                }
+                else if(angular.isString(action.resourceData)) {
+                    data = data[action.resourceData];
+                }
+                else {
+                    throw $resourceMinErr('badresourceloc',
+                        "Error in resource data configuration. " +
+                          "Expected string or function, got {0}", typeof action.resourceData);
+                }
+            }
+
             if (data) {
               // Need to convert action.isArray to boolean in case it is undefined
               // jshint -W018

test/ngResource/resourceSpec.js

@@ -1200,6 +1200,97 @@ describe("resource", function() {
       expect(item).toEqualData({id: 'abc'});
     });
   });
+
+  describe('wrapped responses', function()
+  {
+    var objectResponse = {meta: {metaField: 'value'}, data: {id: 123}};
+    var listResponse = {meta: {metaField: 'value'}, items: [{id: 123}]};
+
+    it('should get resource object from wrapped response via a string', function() {
+      var Person = $resource('/Person/:id', {id: '@id'}, {
+        get: {
+          method: 'GET',
+          resourceData: 'data'
+        }
+      });
+
+      $httpBackend.expect('GET', '/Person/123').respond(objectResponse);
+
+      var p = Person.get({id: 123});
+      $httpBackend.flush();
+
+      expect(p.meta).not.toBeDefined();
+      expect(p.id).toEqual(123);
+      expect(p.$save).toBeDefined();
+    });
+
+    it('should get resource object from wrapped response via a function', function()
+    {
+      var Person = $resource('/Person/:id', {id: '@id'}, {
+        get: {
+          method: 'GET',
+          resourceData: function(response)
+          {
+            return response.data;
+          }
+        }
+      });
+
+      $httpBackend.expect('GET', '/Person/123').respond(objectResponse);
+
+      var p = Person.get({id: 123});
+      $httpBackend.flush();
+
+      expect(p.meta).not.toBeDefined();
+      expect(p.id).toEqual(123);
+      expect(p.$save).toBeDefined();
+    });
+
+    it('should get resource list from wrapped response via string', function()
+    {
+      var Person = $resource('/Person/:id', {id: '@id'}, {
+        query: {
+          method: 'GET',
+          isArray: true,
+          resourceData: 'items'
+        }
+      });
+
+      $httpBackend.expect('GET', '/Person').respond(listResponse);
+
+      var people = Person.query();
+      $httpBackend.flush();
+
+      var p = people[0];
+
+      expect(p.id).toEqual(123);
+      expect(p.$save).toBeDefined();
+    });
+
+    it('should get resource list from wrapped response via function', function()
+    {
+      var Person = $resource('/Person/:id', {id: '@id'}, {
+        query: {
+          method: 'GET',
+          isArray: true,
+          resourceData: function(response)
+          {
+            return response.items;
+          }
+        }
+      });
+
+      $httpBackend.expect('GET', '/Person').respond(listResponse);
+
+      var people = Person.query();
+      $httpBackend.flush();
+
+      var p = people[0];
+
+      expect(p.id).toEqual(123);
+      expect(p.$save).toBeDefined();
+    });
+  });
 });
 
 describe('resource', function() {
@@ -1251,5 +1342,73 @@ describe('resource', function() {
       )
   });
 
+  it('should fail if responseData is an object', function() {
+    var successSpy = jasmine.createSpy('successSpy');
+    var failureSpy = jasmine.createSpy('failureSpy');
+
+    $httpBackend.expect('GET', '/Person/123').respond({meta: {metaField: 'value'}, data: {id: 123}});
+
+    var Person = $resource('/Person/:id', {id: '@id'}, {
+      get: {
+        method: 'GET',
+        resourceData: {}
+      }
+    });
+
+    Person.get({id: 123}).$promise.then(successSpy, function(e) { failureSpy(e.message); });
+    $httpBackend.flush();
+
+    expect(successSpy).not.toHaveBeenCalled();
+    expect(failureSpy).toHaveBeenCalled();
+    expect(failureSpy.mostRecentCall.args[0]).toMatch(
+      /^\[\$resource:badresourceloc\] Error in resource data configuration\. Expected string or function, got object/
+    );
+  });
+
+  it('should fail if responseData is an array', function() {
+    var successSpy = jasmine.createSpy('successSpy');
+    var failureSpy = jasmine.createSpy('failureSpy');
+
+    $httpBackend.expect('GET', '/Person/123').respond({meta: {metaField: 'value'}, data: {id: 123}});
+
+    var Person = $resource('/Person/:id', {id: '@id'}, {
+      get: {
+        method: 'GET',
+        resourceData: []
+      }
+    });
+
+    Person.get({id: 123}).$promise.then(successSpy, function(e) { failureSpy(e.message); });
+    $httpBackend.flush();
+
+    expect(successSpy).not.toHaveBeenCalled();
+    expect(failureSpy).toHaveBeenCalled();
+    expect(failureSpy.mostRecentCall.args[0]).toMatch(
+      /^\[\$resource:badresourceloc\] Error in resource data configuration\. Expected string or function, got object/
+    );
+  });
+
+  it('should fail if responseData is a number', function() {
+    var successSpy = jasmine.createSpy('successSpy');
+    var failureSpy = jasmine.createSpy('failureSpy');
+
+    $httpBackend.expect('GET', '/Person/123').respond({meta: {metaField: 'value'}, data: {id: 123}});
+
+    var Person = $resource('/Person/:id', {id: '@id'}, {
+      get: {
+        method: 'GET',
+        resourceData: 123
+      }
+    });
+
+    Person.get({id: 123}).$promise.then(successSpy, function(e) { failureSpy(e.message); });
+    $httpBackend.flush();
+
+    expect(successSpy).not.toHaveBeenCalled();
+    expect(failureSpy).toHaveBeenCalled();
+    expect(failureSpy.mostRecentCall.args[0]).toMatch(
+      /^\[\$resource:badresourceloc\] Error in resource data configuration\. Expected string or function, got number/
+    );
+  });
 
 });