feat(utils): #45 - Enforce type for custom remote, and add a jsonapi option on custom remote to override include/exclude

Tronix117 · Tronix117 · commit b766dd07dc00 · 2018-01-15T10:37:36.000+01:00
feat(options): Add a `handleCustomRemote: boolean` option to component config
diff --git a/README.md b/README.md
@@ -119,6 +119,7 @@ Example:
     "enable": true,
     "handleErrors": true,
     "errorStackInResponse": false,
+    "handleCustomRemote": false,
     "exclude": [
       {"model": "comment"},
       {"methods": "find"},
@@ -220,6 +221,26 @@ response. It will be stored under the `source.stack` key.
 - Type: `boolean`
 - Default: `false`
 
+### handleCustomRemote
+Allow all (custom) remotes to be serialized by default.
+
+This option can be overrided with:
+1. `jsonapi` remote option (have highest priority)
+2. `exclude` component option
+3. `include` component option
+
+#### example
+```js
+{
+  ...
+  "handleCustomRemote": true,
+  ...
+}
+```
+
+- Type: `boolean`
+- Default: `false`
+
 ### exclude
 Allows blacklisting of models and methods.
 Define an array of blacklist objects. Blacklist objects can contain "model" key
@@ -388,6 +409,55 @@ Only expose foreign keys for the comment model findById method. eg. `GET /api/co
 - Type: `boolean|array`
 - Default: `false`
 
+## Custom remote
+
+### `jsonapi` remote options
+Sometime you need to control if custom remote should be serialized or not.
+**By default a custom remote will NOT be handled by JSONApi.**
+
+To enabled/disable JSONApi for specific remotes, you have multiple solutions:
+
+1. Use `jsonapi` remote option
+2. Use `exlude` on component options (see above)
+3. Use `include` on component options (see above)
+4. Use `handleCustomRemote` on component options (see above)
+
+**This option has precedence** and it forces the remote to BE or to NOT BE deserialized/serialized by JSONApi.
+
+#### examples
+```js
+Post.remoteMethod('greet', {
+  jsonapi: true
+  returns: { root: true }
+})
+```
+Ensure the response of `Post.greet` will follow the JSONApi format.
+
+```js
+Post.remoteMethod('greet', {
+  jsonapi: false
+  returns: { arg: 'greeting', type: 'string' }
+})
+```
+Ensure the response of `Post.greet` will not follow the JSONApi format.
+
+#### Note
+You should always pass `root: true` to the `returns` object when you use JSONApi, especialy when you expect to respond with an array.
+
+### Override serialization type
+You may want for a custom method of a given model to return instance(s) from another model. When you do so, you need to enforce the return `type` of this other model in the definition of the remote method.
+
+*If an unknown type or no type are given, the model name will be used.*
+
+#### example
+
+```js
+Post.remoteMethod('prototype.ownComments', {
+  jsonapi: true
+  returns: { root: true, type: 'comment' }
+})
+```
+
 ## Custom Serialization
 For occasions where you need greater control over the serialization process, you can implement a custom serialization function for each model as needed. This function will be used instead of the regular serialization process.
 
diff --git a/lib/utils.js b/lib/utils.js
@@ -11,6 +11,7 @@ module.exports = {
   buildModelUrl: buildModelUrl,
   clone: clone,
   getModelFromContext: getModelFromContext,
+  getTypeFromContext: getTypeFromContext,
   getRelationsFromContext: getRelationsFromContext,
   hostFromContext: hostFromContext,
   modelNameFromContext: modelNameFromContext,
@@ -126,10 +127,32 @@ function urlFromContext (context) {
  * @return {Object}
  */
 function getModelFromContext (context, app) {
+  var type = getTypeFromContext(context)
+  if (app.models[type]) return app.models[type]
+
   var name = modelNameFromContext(context)
   return app.models[name]
 }
 
+/**
+ * Returns a model type from the context object.
+ * Infer the type from the `root` returns in the remote.
+ * @public
+ * @memberOf {Utils}
+ * @param {Object} context
+ * @param {Object} app
+ * @return {String}
+ */
+function getTypeFromContext (context) {
+  if (!context.method.returns) return undefined
+
+  const returns = [].concat(context.method.returns)
+  for (var i = 0, l = returns.length; i < l; i++) {
+    if (typeof returns[i] === 'object' && returns[i].root === true) continue
+    return returns[i].type
+  }
+}
+
 /**
  * Gets the relations from a context.
  * @public
@@ -192,31 +215,40 @@ function buildModelUrl (protocol, host, apiRoot, modelName, id) {
 }
 
 function shouldApplyJsonApi (ctx, options) {
-  if (!options.include) return false
+  // include on remote have higher priority
+  if (ctx.method.jsonapi) return !!ctx.method.jsonapi
 
   var modelName = ctx.method.sharedClass.name
   var methodName = ctx.method.name
   var model
   var methods
-  for (var i = 0; i < options.include.length; i++) {
-    model = options.include[i].model
-    methods = options.include[i].methods
-    if (model === modelName && !methods) return true
-    if (!model && methods === methodName) return true
-    if (model === modelName && methods === methodName) return true
-    if (model === modelName && _.includes(methods, methodName)) return true
+  if (options.include) {
+    for (var i = 0; i < options.include.length; i++) {
+      model = options.include[i].model
+      methods = options.include[i].methods
+      if (model === modelName && !methods) return true
+      if (!model && methods === methodName) return true
+      if (model === modelName && methods === methodName) return true
+      if (model === modelName && _.includes(methods, methodName)) return true
+    }
   }
-  return false
+
+  // a default option can be set in component-config
+  return !!options.handleCustomRemote
 }
 
 function shouldNotApplyJsonApi (ctx, options) {
+  // exclude on remote have higher priority
+  if (ctx.method.jsonapi === false) return true
+
   // handle options.exclude
   if (!options.exclude) return false
 
   var modelName = ctx.method.sharedClass.name
   var methodName = ctx.method.name
   var model
   var methods
+
   for (var i = 0; i < options.exclude.length; i++) {
     model = options.exclude[i].model
     methods = options.exclude[i].methods
@@ -225,6 +257,7 @@ function shouldNotApplyJsonApi (ctx, options) {
     if (model === modelName && methods === methodName) return true
     if (model === modelName && _.includes(methods, methodName)) return true
   }
+
   return false
 }
 
diff --git a/test/remoteMethods.test.js b/test/remoteMethods.test.js
@@ -4,31 +4,98 @@ var request = require('supertest')
 var loopback = require('loopback')
 var expect = require('chai').expect
 var JSONAPIComponent = require('../')
-var app, Post
+var app, Post, Archive
 
-describe('loopback json api remote methods', function () {
-  beforeEach(function () {
+describe.only('loopback json api remote methods', function () {
+  var autocompleteTitleData = ['Post 1', 'Post 2']
+
+  var archiveData = {
+    id: 10,
+    raw: {
+      id: 1,
+      title: 'Ancient Post 1',
+      content: 'Ancient Content of Post 1'
+    },
+    createdAt: Date.now()
+  }
+
+  var postData = {
+    id: 1,
+    title: 'Post 1',
+    content: 'Content of Post 1'
+  }
+
+  beforeEach(function (done) {
     app = loopback()
     app.set('legacyExplorer', false)
     var ds = loopback.createDataSource('memory')
+
+    Archive = ds.createModel('archive', {
+      id: { type: Number, id: true },
+      raw: Object,
+      createAt: Date
+    })
+
     Post = ds.createModel('post', {
       id: { type: Number, id: true },
       title: String,
       content: String
     })
+
     Post.greet = function (msg, cb) {
       cb(null, 'Greetings... ' + msg)
     }
+
+    Post.last = function (cb) {
+      Post.findOne({}, cb)
+    }
+
+    Post.autocomplete = function (q, cb) {
+      cb(null, autocompleteTitleData)
+    }
+
+    Post.prototype.findArchives = function (cb) {
+      Archive.find({}, cb)
+    }
+
     Post.remoteMethod('greet', {
       accepts: { arg: 'msg', type: 'string' },
       returns: { arg: 'greeting', type: 'string' }
     })
+
+    Post.remoteMethod('last', {
+      returns: { root: true },
+      http: { verb: 'get' }
+    })
+
+    Post.remoteMethod('autocomplete', {
+      jsonapi: false,
+      accepts: { arg: 'q', type: 'string', http: { source: 'query' } },
+      returns: { root: true, type: 'array' },
+      http: { path: '/autocomplete', verb: 'get' }
+    })
+
+    Post.remoteMethod('prototype.findArchives', {
+      jsonapi: true,
+      returns: { root: true, type: 'archive' },
+      http: { path: '/archives' }
+    })
+
     app.model(Post)
+    app.model(Archive)
     app.use(loopback.rest())
-    JSONAPIComponent(app)
+
+    Promise.all([Archive.create(archiveData), Post.create(postData)])
+      .then(function () {
+        done()
+      })
   })
 
-  describe('remote method for application/json', function () {
+  describe('for application/json', function () {
+    beforeEach(function () {
+      JSONAPIComponent(app)
+    })
+
     it('POST /posts/greet should return remote method message', function (done) {
       request(app)
         .post('/posts/greet')
@@ -42,4 +109,96 @@ describe('loopback json api remote methods', function () {
         })
     })
   })
+
+  describe('should serialize with `jsonapi: true`', function () {
+    beforeEach(function () {
+      JSONAPIComponent(app)
+    })
+
+    testAutocompleteJsonAPI()
+    testArchivesJsonAPI()
+  })
+
+  describe('when `serializeCustomRemote` is set', function (done) {
+    beforeEach(function () {
+      JSONAPIComponent(app, { handleCustomRemote: true })
+    })
+
+    testAutocompleteJsonAPI()
+    testArchivesJsonAPI()
+    testLastJsonAPI()
+  })
+
+  /* Static test */
+  function testAutocompleteJsonAPI () {
+    it(
+      'GET /posts/autocomplete should return an array with raw format (`jsonapi: false` has precedence)',
+      function (done) {
+        request(app)
+          .get('/posts/autocomplete')
+          .expect(200)
+          .end(function (err, res) {
+            expect(err).to.equal(null)
+            expect(res.body).to.deep.equal(autocompleteTitleData)
+            done()
+          })
+      }
+    )
+  }
+
+  /* Static test */
+  function testArchivesJsonAPI () {
+    it(
+      'GET /posts/1/archives should return a JSONApi list of Archive (`jsonapi: true` has precedence)',
+      function (done) {
+        request(app)
+          .get('/posts/1/archives')
+          .expect(200)
+          .end(function (err, res) {
+            expect(err).to.equal(null)
+            expect(res.body).to.be.an('object')
+            expect(res.body.data).to.be.an('array').with.lengthOf(1)
+            expect(res.body.data[0].id).to.equal(archiveData.id + '')
+            expect(res.body.data[0].attributes).to.deep.equal({
+              raw: archiveData.raw,
+              createdAt: archiveData.createdAt
+            })
+
+            done()
+          })
+      }
+    )
+  }
+
+  /* Static test */
+  function testLastJsonAPI () {
+    it('GET /posts/last should return a JSONApi Post', function (done) {
+      request(app).get('/posts/last').expect(200).end(function (err, res) {
+        expect(err).to.equal(null)
+
+        expect(res.body.data).to.be.an('object')
+        expect(res.body.data.id).to.equal(postData.id + '')
+        expect(res.body.data.attributes).to.deep.equal({
+          title: postData.title,
+          content: postData.content
+        })
+
+        done()
+      })
+    })
+  }
+
+  /* Static test */
+  function testLastRaw () {
+    it(
+      'GET /posts/last should return a raw Post (exclude is more important than include and handleCustomRemote)',
+      function (done) {
+        request(app).get('/posts/last').expect(200).end(function (err, res) {
+          expect(err).to.equal(null)
+          expect(res.body).to.deep.equal(postData)
+          done()
+        })
+      }
+    )
+  }
 })
