Replace raw result array with CollectionProxy

This wraps the results of any collection requests in an CollectionProxy
instance, which allows users to access additional metadata about the
result set. Users can call `CollectionProxy.data` to get the parsed model
array, or may access the original request body with `CollectionProxy.raw`.
Additionally, the `meta` field of the response is exposed as a
first-class member, in `CollectionProxy#meta`.

Follow-up items include similar wrapping for scope and model methods
that are expecting a single result, wrapping them in a `RecordProxy` or
something similar.

Author: wadetandy

index.d.ts

@@ -14,6 +14,7 @@ declare module NodeJS  {
 interface japiDoc {
   data: any; // can't do Array | japiResource
   included: Array<japiResource>;
+  meta?: any;
 }
 
 interface japiResourceIdentifier {

src/associations.ts

@@ -1,5 +1,6 @@
 import Attribute from './attribute';
 import Model from './model';
+import CollectionProxy from './collection-proxy';
 
 class Base extends Attribute {
   klass: typeof Model;

src/collection-proxy.ts

@@ -0,0 +1,48 @@
+import Model from './model';
+
+class CollectionProxy<T> {
+  private _raw_json : japiDoc;
+  private _array : Array<T>;
+
+  constructor (raw_json : japiDoc = { data: [], included: [] }) {
+    this.setRaw(raw_json)
+  }
+
+  get raw () : japiDoc {
+    return this._raw_json
+  }
+
+  get data () : Array<T> {
+    return this._array
+  }
+
+  get collection () : Array<T> {
+    return this._array
+  }
+
+  get meta () : Object {
+    if (this.raw) {
+      return this.raw.meta || {}
+    }
+
+    return {}
+  }
+
+  map (fn) {
+    return this.data.map(fn)
+  }
+
+  private setRaw = (json_payload : japiDoc) => {
+    this._raw_json = json_payload
+
+    this._array = []
+
+    if (this.raw.data) {
+      this.raw.data.map((datum : japiResource) => {
+        this._array.push(Model.fromJsonapi(datum, this.raw));
+      });
+    }
+  }
+}
+
+export default CollectionProxy

src/model.ts

@@ -4,6 +4,7 @@ import Scope from './scope';
 import Config from './configuration';
 import Attribute from './attribute';
 import deserialize from './util/deserialize';
+import CollectionProxy from './collection-proxy';
 import _extend from './util/extend';
 import { camelize } from './util/string';
 
@@ -41,7 +42,7 @@ export default class Model {
     this.attributes = attributes;
   }
 
-  static all() : Promise<Array<Model>> {
+  static all() : Promise<CollectionProxy<Model>> {
     return this.scope().all();
   }
 

src/scope.ts

@@ -2,6 +2,7 @@ import Model from './model';
 import Config from './configuration';
 import parameterize from './util/parameterize';
 import IncludeDirective from './util/include-directive';
+import CollectionProxy from './collection-proxy';
 import Request from './request';
 import colorize from './util/colorize';
 
@@ -19,11 +20,11 @@ export default class Scope {
     this.model = model;
   }
 
-  all() : Promise<Array<Model>> {
+  all() : Promise<CollectionProxy<Model>> {
     return this._fetch(this.model.url()).then((json : japiDoc) => {
-      return json.data.map((datum : japiResource) => {
-        return Model.fromJsonapi(datum, json);
-      });
+      let collection = new CollectionProxy(json)
+
+      return  collection
     });
   }
 
@@ -35,8 +36,8 @@ export default class Scope {
 
   // TODO: paginate 1
   first() : Promise<Model> {
-    return this.per(1).all().then((models : Array<Model>) => {
-      return models[0];
+    return this.per(1).all().then((models : CollectionProxy<Model>) => {
+      return models.data[0];
     });
   }
 

test/integration/finders-test.ts

@@ -7,6 +7,12 @@ after(function () {
   fetchMock.restore();
 });
 
+let resultData = function(promise) {
+  return promise.then(function(collection) {
+    return collection.data
+  })
+}
+
 describe('Model finders', function() {
   describe('#find()', function() {
     before(function () {
@@ -71,7 +77,8 @@ describe('Model finders', function() {
   });
 
   describe('#all()', function() {
-    before(function () {
+    beforeEach(function () {
+      fetchMock.restore();
       fetchMock.get('http://example.com/api/v1/people', {
         data: [
           { id: '1', type: 'people' }
@@ -80,10 +87,33 @@ describe('Model finders', function() {
     });
 
     it('returns a promise that resolves the correct instances', function() {
-      return expect(Person.all()).to.eventually
+      return expect(resultData(Person.all())).to.eventually
         .all.be.instanceof(Person)
         .all.have.property('id', '1')
     });
+
+    describe('response includes a meta payload', function() {
+      beforeEach(function () {
+        fetchMock.restore();
+        fetchMock.get('http://example.com/api/v1/people', {
+          data: [
+            { id: '1', type: 'people' }
+          ],
+          meta: {
+            stats: {
+              total: {
+                count: 45
+              },
+            }
+          }
+        });
+      });
+
+      it('promise collection includes meta payload', function() {
+        return expect(Person.all()).to.eventually
+          .have.deep.property('meta.stats.total.count', 45)
+      });
+    });
   });
 
   describe('#page', function() {
@@ -96,25 +126,24 @@ describe('Model finders', function() {
     });
 
     it('queries correctly', function() {
-      return expect(Person.page(2).all()).to.eventually
+      return expect(resultData(Person.page(2).all())).to.eventually
         .all.be.instanceof(Person)
         .all.have.property('id', '2')
     });
   });
 
   describe('#per', function() {
     before(function () {
-      fetchMock.get('http://example.com/api/v1/people?page[size]=10', {
+      fetchMock.get('http://example.com/api/v1/people?page[size]=2', {
         data: [
-          { id: '2', type: 'people' }
+          { id: '1', type: 'people' }
         ]
       });
     });
 
     it('queries correctly', function() {
-      return expect(Person.page(2).all()).to.eventually
+      return expect(resultData(Person.per(2).all())).to.eventually
         .all.be.instanceof(Person)
-        .all.have.property('id', '2')
     });
   });
 
@@ -128,7 +157,7 @@ describe('Model finders', function() {
     });
 
     it('queries correctly', function() {
-      return expect(Person.order('foo').order({ bar: 'desc' }).all()).to.eventually
+      return expect(resultData(Person.order('foo').order({ bar: 'desc' }).all())).to.eventually
         .all.be.instanceof(Person)
         .all.have.property('id', '2')
     });
@@ -144,7 +173,7 @@ describe('Model finders', function() {
     });
 
     it('queries correctly', function() {
-      return expect(Person.where({ id: 2 }).where({ a: 'b' }).all()).to.eventually
+      return expect(resultData(Person.where({ id: 2 }).where({ a: 'b' }).all())).to.eventually
         .all.be.instanceof(Person)
         .all.have.property('id', '2')
     });
@@ -160,7 +189,7 @@ describe('Model finders', function() {
     });
 
     it('queries correctly', function() {
-      return expect(Person.select({ people: ['name', 'age'] }).all()).to.eventually
+      return expect(resultData(Person.select({ people: ['name', 'age'] }).all())).to.eventually
         .all.be.instanceof(Person)
         .all.have.property('id', '2')
     });
@@ -176,7 +205,7 @@ describe('Model finders', function() {
     });
 
     it('queries correctly', function() {
-      return expect(Person.selectExtra({ people: ['net_worth', 'best_friend'] }).all()).to.eventually
+      return expect(resultData(Person.selectExtra({ people: ['net_worth', 'best_friend'] }).all())).to.eventually
         .all.be.instanceof(Person)
         .all.have.property('id', '2')
     });
@@ -195,7 +224,7 @@ describe('Model finders', function() {
     });
 
     it('queries correctly', function() {
-      return expect(Person.includes({ a: ['b', { c: 'd' }] }).all()).to.eventually
+      return expect(resultData(Person.includes({ a: ['b', { c: 'd' }] }).all())).to.eventually
         .all.be.instanceof(Person)
         .all.have.property('id', '2')
     });

test/unit/collection-proxy-test.ts

@@ -0,0 +1,60 @@
+import { sinon } from '../../test/test-helper';
+import { Person } from '../fixtures';
+
+import CollectionProxy from '../../src/collection-proxy'
+
+beforeEach(function() {
+});
+
+describe('CollectionProxy', function() {
+  let personData = {
+    data: [
+      {
+        id: '1',
+        type: 'people',
+        attributes: {
+          firstName: 'Donald',
+          lastName: 'Budge'
+        },
+      }
+    ],
+    included: [],
+    meta: {
+      stats: {
+        total: {
+          count: 3
+        },
+        average: {
+          salary: "$100k"
+        }
+      }
+    }
+  }
+
+  describe('initialization', function() {
+    it('should assign the response correctly', function() {
+      let collection = new CollectionProxy(personData)
+      expect(collection.raw).to.deep.equal(personData)
+    })
+
+    it('should assign the correct models to the data array', function() {
+      let collection = new CollectionProxy(personData)
+      expect(collection.data).all.to.be.instanceof(Person)
+    })
+  })
+
+  describe('#meta', function() {
+    it('should get meta field from raw response', function() {
+      let collection = new CollectionProxy(personData)
+      expect(collection.meta).to.eq(personData.meta)
+    })
+  })
+
+  describe('#collection', function() {
+    it('should alias the data field', function() {
+      let collection = new CollectionProxy(personData)
+      expect(collection.collection).to.eq(collection.data)
+    })
+  })
+})
+

test/unit/model-test.ts

@@ -174,7 +174,7 @@ describe('Model', function() {
 
     it('skips relationships without data', function() {
       let instance = Model.fromJsonapi(doc.data, doc);
-      expect(instance.tags).to.eql([]);
+      expect(instance.tags.length).to.eql(0);
     });
   });
 });

test/unit/relationships-test.ts

@@ -3,6 +3,8 @@
 import { sinon } from '../../test/test-helper';
 import { Author, Genre } from '../fixtures';
 
+import CollectionProxy from '../../src/collection-proxy';
+
 describe('Model relationships', function() {
   it('supports direct assignment of models', function() {
     let author = new Author();
@@ -31,8 +33,8 @@ describe('Model relationships', function() {
     expect(author.genre.name).to.eq('Horror');
   });
 
-  it('defaults hasMany to empty array', function() {
+  it('defaults hasMany to empty collection', function() {
     let genre = new Genre();
-    expect(genre.authors).to.eql([]);
+    expect(genre.authors.length).to.eql(0);
   });
 });