Feature: .prop()

Author: codeclown

README.md

@@ -132,6 +132,12 @@ request
 
 // You can use async/await of course
 const { status, body } = await request.get('http://example.com')
+
+// Helper method to return a nested value from the request
+const status = await request.get('https://example.com/accounts.json').prop('status')
+const contentType = await request.get('https://example.com/accounts.json').prop(['headers', 'content-type'])
+const data = await request.get('https://example.com/accounts.json').prop('data')
+const account = await request.get('https://example.com/accounts.json').prop('data.accounts[0]')
 ```
 
 
@@ -154,6 +160,7 @@ The following methods are available.
 - [.urlencoded(value)](#urlencoded)
 - [.timeout(milliseconds)](#timeout)
 - [.unsetTimeout()](#unsettimeout)
+- [.prop(path)](#prop)
 - [.send([body])](#send)
 - [.sendUrlencoded(data)](#sendurlencoded)
 - [.sendJson(data)](#sendjson)
@@ -355,6 +362,23 @@ Removes the timeout-value previously set with [`timeout`](#timeout).
 .unsetTimeout()
 ```
 
+### prop
+
+Sets a path (similar to [`lodash.get`](https://lodash.com/docs/4.17.15#get)) which will be resolved once the response is returned.
+
+```js
+.prop(path)
+```
+
+Where `path` is a string or an array.
+
+Example:
+
+```js
+cosnt account = await request.get('...').prop('data.accounts[0]');
+cosnt contentType = await request.get('...').prop(['headers', 'content-type']);
+```
+
 ### send
 
 Dispatches the request and returns a `Promise`.

build/yea.js

@@ -75,7 +75,8 @@
     return assign({}, config, updated, {
       headers: assign({}, config.headers, updated.headers || {}),
       responseTransformers: [].concat(updated.responseTransformers || config.responseTransformers),
-      polyfills: assign({}, config.polyfills, updated.polyfills || {})
+      polyfills: assign({}, config.polyfills, updated.polyfills || {}),
+      prop: [].concat(updated.prop || config.prop),
     });
   }
 
@@ -86,6 +87,21 @@
     return response;
   }
 
+  function parsePropPath(path) {
+    if (Array.isArray(path)) {
+      return path;
+    }
+    return path.replace(/\]$/, '').replace(/[[\]]/g, '.').split('.');
+  }
+
+  function applyPropPath(object, path) {
+    var value = object;
+    for (var i = 0; i < path.length; i++) {
+      value = value[path[i]];
+    }
+    return value;
+  }
+
   function YeaAjaxRequest(config) {
     this._config = config;
     this.jsonResponseTransformer = jsonResponseTransformer;
@@ -95,7 +111,9 @@
     this.utils = {
       assign: assign,
       toQueryString: toQueryString,
-      createUrl: createUrl
+      createUrl: createUrl,
+      parsePropPath: parsePropPath,
+      applyPropPath: applyPropPath
     };
   }
 
@@ -215,6 +233,17 @@
     return new YeaAjaxRequest(mergeConfig(this._config, { timeout: null }));
   };
 
+  YeaAjaxRequest.prototype.prop = function prop(path) {
+    if (path === null || path === '') {
+      path = [];
+    } else if (typeof path === 'string') {
+      path = parsePropPath(path);
+    } else if (!Array.isArray(path)) {
+      throw new Error('Expected a string (e.g. "data.items[0]") or an array for prop');
+    }
+    return new YeaAjaxRequest(mergeConfig(this._config, { prop: path }));
+  };
+
   YeaAjaxRequest.prototype.setResponseTransformers = function setResponseTransformers(transformers) {
     if (!Array.isArray(transformers)) {
       throw new Error('Expected an array of response transformers');
@@ -318,6 +347,9 @@
               if (timeoutId) {
                 clearTimeout(timeoutId);
               }
+
+              response = applyPropPath(response, config.prop);
+
               resolve(response);
             } else {
               var error = new Error('Request failed with status ' + response.status);
@@ -363,6 +395,7 @@
     headers: {},
     allowedStatusCode: /^2[0-9]{2}$/,
     timeout: null,
+    prop: [],
     responseTransformers: [
       jsonResponseTransformer
     ],

build/yea.min.js

@@ -49,11 +49,11 @@
   "bundlesize": [
     {
       "path": "./build/yea.js",
-      "maxSize": "2.8KB"
+      "maxSize": "3.0KB"
     },
     {
       "path": "./build/yea.min.js",
-      "maxSize": "2.4KB"
+      "maxSize": "2.6KB"
     }
   ],
   "scripts": {

package.json

@@ -75,7 +75,8 @@
     return assign({}, config, updated, {
       headers: assign({}, config.headers, updated.headers || {}),
       responseTransformers: [].concat(updated.responseTransformers || config.responseTransformers),
-      polyfills: assign({}, config.polyfills, updated.polyfills || {})
+      polyfills: assign({}, config.polyfills, updated.polyfills || {}),
+      prop: [].concat(updated.prop || config.prop),
     });
   }
 
@@ -86,6 +87,21 @@
     return response;
   }
 
+  function parsePropPath(path) {
+    if (Array.isArray(path)) {
+      return path;
+    }
+    return path.replace(/\]$/, '').replace(/[[\]]/g, '.').split('.');
+  }
+
+  function applyPropPath(object, path) {
+    var value = object;
+    for (var i = 0; i < path.length; i++) {
+      value = value[path[i]];
+    }
+    return value;
+  }
+
   function YeaAjaxRequest(config) {
     this._config = config;
     this.jsonResponseTransformer = jsonResponseTransformer;
@@ -95,7 +111,9 @@
     this.utils = {
       assign: assign,
       toQueryString: toQueryString,
-      createUrl: createUrl
+      createUrl: createUrl,
+      parsePropPath: parsePropPath,
+      applyPropPath: applyPropPath
     };
   }
 
@@ -215,6 +233,17 @@
     return new YeaAjaxRequest(mergeConfig(this._config, { timeout: null }));
   };
 
+  YeaAjaxRequest.prototype.prop = function prop(path) {
+    if (path === null || path === '') {
+      path = [];
+    } else if (typeof path === 'string') {
+      path = parsePropPath(path);
+    } else if (!Array.isArray(path)) {
+      throw new Error('Expected a string (e.g. "data.items[0]") or an array for prop');
+    }
+    return new YeaAjaxRequest(mergeConfig(this._config, { prop: path }));
+  };
+
   YeaAjaxRequest.prototype.setResponseTransformers = function setResponseTransformers(transformers) {
     if (!Array.isArray(transformers)) {
       throw new Error('Expected an array of response transformers');
@@ -318,6 +347,9 @@
               if (timeoutId) {
                 clearTimeout(timeoutId);
               }
+
+              response = applyPropPath(response, config.prop);
+
               resolve(response);
             } else {
               var error = new Error('Request failed with status ' + response.status);
@@ -363,6 +395,7 @@
     headers: {},
     allowedStatusCode: /^2[0-9]{2}$/,
     timeout: null,
+    prop: [],
     responseTransformers: [
       jsonResponseTransformer
     ],

src/index.js

@@ -2,7 +2,7 @@ describe('Methods', function () {
   describe('defaults', function () {
     it('has defaults', function () {
       var defaults = yea.toObject();
-      expect(defaults).to.have.keys(['method', 'baseUrl', 'url', 'query', 'body', 'headers', 'responseTransformers', 'allowedStatusCode', 'timeout', 'polyfills']);
+      expect(defaults).to.have.keys(['method', 'baseUrl', 'url', 'query', 'body', 'headers', 'responseTransformers', 'allowedStatusCode', 'timeout', 'prop', 'polyfills']);
       expect(defaults.method).to.equal('GET');
       expect(defaults.baseUrl).to.equal('');
       expect(defaults.url).to.equal('');
@@ -12,6 +12,7 @@ describe('Methods', function () {
       expect(defaults.responseTransformers).to.deep.equal([yea.jsonResponseTransformer]);
       expect(defaults.allowedStatusCode).to.deep.equal(/^2[0-9]{2}$/);
       expect(defaults.timeout).to.equal(null);
+      expect(defaults.prop).to.deep.equal([]);
       expect(defaults.polyfills).to.deep.equal({});
     });
   });
@@ -350,6 +351,43 @@ describe('Methods', function () {
     });
   });
 
+  describe('.prop', function () {
+    it('sets prop', function () {
+      expect(yea.prop(null).toObject().prop).to.deep.equal([]);
+      expect(yea.prop('').toObject().prop).to.deep.equal([]);
+      expect(yea.prop('data.accounts[0]').toObject().prop).to.deep.equal(['data', 'accounts', '0']);
+      expect(yea.prop(['data', 'accounts', '0']).toObject().prop).to.deep.equal(['data', 'accounts', '0']);
+    });
+
+    it('throws on unexpected type', function () {
+      expect(function () {
+        yea.prop({});
+      }).to.throw('Expected a string (e.g. "data.items[0]") or an array for prop');
+
+      expect(function () {
+        yea.prop(function () {});
+      }).to.throw('Expected a string (e.g. "data.items[0]") or an array for prop');
+
+      expect(function () {
+        yea.prop(123);
+      }).to.throw('Expected a string (e.g. "data.items[0]") or an array for prop');
+    });
+
+    it('leaves no reference to the array', function () {
+      var array = ['headers', 'content-type'];
+      var req = yea.prop(array);
+      expect(req.toObject().prop).to.not.equal(array);
+      array.splice(0, 1);
+      expect(req.toObject().prop).to.deep.equal(['headers', 'content-type']);
+    });
+
+    it('is immutable', function () {
+      var req = yea.prop('data');
+      expect(req).to.not.equal(yea);
+      expect(req.constructor).to.equal(yea.constructor);
+    });
+  });
+
   describe('.send', function () {
     it('exists (see requests.spec.js for more tests)', function () {
       expect(yea.send).to.be.ok;

test/specs/methods.spec.js

@@ -224,6 +224,30 @@ describe('Requests', function () {
       });
   });
 
+  it('returns property via .prop()', function () {
+    return yea
+      .method('get')
+      .url('/json-payload')
+      .prop('data')
+      .send()
+      .then(function (body) {
+        expect(body).to.deep.equal({
+          taker: 'believer'
+        });
+      });
+  });
+
+  it('returns nested property via .prop()', function () {
+    return yea
+      .method('get')
+      .url('/json-payload')
+      .prop('data.taker')
+      .send()
+      .then(function (value) {
+        expect(value).to.equal('believer');
+      });
+  });
+
   it('throws on 404', function () {
     var error;
     return yea

test/specs/requests.spec.js

@@ -81,4 +81,39 @@ describe('utils', function () {
       expect(yea.utils.createUrl('', 'accounts', 'foo=bar')).to.equal('accounts?foo=bar');
     });
   });
+
+  describe('.parsePropPath', function () {
+    it('parses path', function () {
+      // Simple dot notation
+      expect(yea.utils.parsePropPath('data')).to.deep.equal(['data']);
+      expect(yea.utils.parsePropPath('headers')).to.deep.equal(['headers']);
+      expect(yea.utils.parsePropPath('data.accounts')).to.deep.equal(['data', 'accounts']);
+      // Array indices
+      expect(yea.utils.parsePropPath('data.accounts[0]')).to.deep.equal(['data', 'accounts', '0']);
+      expect(yea.utils.parsePropPath('data.accounts[1]')).to.deep.equal(['data', 'accounts', '1']);
+    });
+  });
+
+  describe('.applyPropPath', function () {
+    it('picks requested value from object', function () {
+      var response = {
+        headers: {
+          'content-type': 'application/json'
+        },
+        data: {
+          accounts: [
+            { name: 'Account 1' },
+            { name: 'Account 2' }
+          ]
+        }
+      };
+      expect(yea.utils.applyPropPath(response, [])).to.equal(response);
+      expect(yea.utils.applyPropPath(response, ['headers'])).to.equal(response.headers);
+      expect(yea.utils.applyPropPath(response, ['data'])).to.equal(response.data);
+      expect(yea.utils.applyPropPath(response, ['data', 'accounts'])).to.equal(response.data.accounts);
+      expect(yea.utils.applyPropPath(response, ['data', 'accounts', '0'])).to.equal(response.data.accounts['0']);
+      expect(yea.utils.applyPropPath(response, ['data', 'accounts', '1'])).to.equal(response.data.accounts['1']);
+      expect(yea.utils.applyPropPath(response, ['headers', 'content-type'])).to.equal(response.headers['content-type']);
+    });
+  });
 });