Add methods to 'write' to relationship URLs.

Author: mrichar1

README.md

@@ -208,7 +208,7 @@ The 3 categories of Vuex methods are used as follows:
 
 The usual way to use this module is to use `actions` wherever possible. All actions are asynchronous, and both query the API and update the store, then return data in a normalized form. Actions can be handled using the `then/catch` methods of promises, or using `async/await`.
 
-#### RESTful actions
+#### 'Direct' Actions
 
 There are 4 actions (with aliases): `get` (`fetch`), `post` (`create`), `patch` (`update`), and `delete` which correspond to RESTful methods.
 
@@ -232,7 +232,7 @@ this.$store.dispatch('jv/get', 'widget').then((data) => {
   console.log(data)
 })
 
-// Request Query params (JSONAPI options, auth tokens etc)
+// axios request query params (JSONAPI options, auth tokens etc)
 const params = {
   token: 'abcdef123456',
 }
@@ -272,6 +272,9 @@ this.$store.dispatch('jv/get', ['widget/1', { params: params }]).then((widget1)
   widget1['color'] = 'red'
   this.$store.dispatch('jv/patch', [widget1, { params: params }])
 })
+
+// Delete a widget from the API
+this.$store.dispatch('jv/delete', ['widget/1', { params: params }])
 ```
 
 #### search
@@ -288,6 +291,10 @@ const widgetSearch = (text) => {
 }
 ```
 
+#### 'Relationship' Actions
+
+There are also 4 'relationship' actions: `getRelated`, `postRelated`, `patchRelated` and `deleteRelated` which modify relationships via an object's relationship URL.
+
 #### getRelated
 
 _Note_ - in many cases you may prefer to use the jsonapi server-side `include` option to get data on relationships included in your original query. (See [Relationships](#relationships)).
@@ -368,6 +375,56 @@ this.$store.dispatch('jv/getRelated', customRels).then((data) => {
 })
 ```
 
+#### (delete|patch|post)Related
+
+The other 3 methods are all for 'writing' to the relationships of an object. they use the `relationship URLs` of an object, rather than writing to the object itself.
+
+* `post` - adds relationships to an item.
+* `delete` - removes relationships from an item.
+* `patch` - replace all relationships for an item.
+
+All methods return the updated item from the API, and also update the store (by internally calling the `get` action).
+
+These methods take a single argument - an object representing the item, with the `'_jv` section containing relationships that are to be acted on. For example:
+
+```js
+const rels = {
+  _jv: {
+    type: 'widget',
+    id: '1',
+    relationships: {
+      widgets: {
+        data: {
+          type: 'widget',
+          id: '2',
+        },
+      },
+      doohickeys: {
+        data: {
+          type: 'doohickeys',
+          id: '10',
+        },
+      },
+    },
+  },
+}
+
+// Adds 'widget/2' and 'doohickey/10' relationships to 'widgets' and 'doohickeys' on 'widget/1'
+this.$store.dispatch('jv/postRelated', rels).then((data) => {
+  console.log(data)
+})
+
+// Removes 'widget/2' and 'doohickey/10' relationships from 'widgets' and 'doohickeys' on 'widget/1'
+this.$store.dispatch('jv/deleteRelated', rels).then((data) => {
+  console.log(data)
+})
+
+// Replaces 'widgets' and 'doohickeys' relationships with just 'widget/1' and 'doohickey/10'
+this.$store.dispatch('jv/patchRelated', rels).then((data) => {
+  console.log(data)
+})
+```
+
 #### Error Handling
 
 Most errors are likely to be those raised by the API in response to the request. These will take the form of an [Axios Error Handling](https://github.com/axios/axios#handling-errors) object, containing an [JSONAPI Error object](https://jsonapi.org/format/#error-objects).

src/actions.js

@@ -18,6 +18,52 @@ import { utils } from './jsonapi-vuex'
 const actions = (api, conf) => {
   // Short var name
   let jvtag = conf['jvtag']
+
+  /**
+   * Internal method to 'write' related items from the API.
+   * This method is wrapped by `(delete|patch|post)Related` actions, and is not available directly as an action.
+   *
+   * @async
+   * @memberof module:jsonapi-vuex.jsonapiModule.actions
+   * @param {object} context - Vuex context object
+   * @param {object} args - A restructured object, specifying relationship(s)  - e.g. `{ _jv: { type: "endpoint", id: "1", relationships: {...} } }`
+   * @param {object} args - A restructured object, specifying relationship(s)  - e.g. `{ _jv: { type: "endpoint", id: "1", relationships: {...} } }`
+   * @return {object} Restructured representation of the 'parent' item
+   */
+  const writeRelated = async (context, args, method) => {
+    let [data, config] = utils.unpackArgs(args)
+    let [type, id] = utils.getTypeId(data)
+    if (!type || !id) {
+      throw 'No type/id specified'
+    }
+
+    let rels
+    if (typeof data === 'object' && utils.hasProperty(data[jvtag], 'relationships')) {
+      rels = data[jvtag]['relationships']
+    } else {
+      throw 'No relationships specified'
+    }
+
+    // Iterate over all records in rels
+    let relPromises = []
+    for (let [relName, relItems] of Object.entries(rels)) {
+      if (utils.hasProperty(relItems, 'data')) {
+        let path = `${type}/${id}/relationships/${relName}`
+        const apiConf = {
+          method: method,
+          url: path,
+          data: relItems,
+        }
+        merge(apiConf, config)
+        relPromises.push(api(apiConf))
+      }
+    }
+    // Wait for all individual API calls to complete
+    await Promise.all(relPromises)
+    // Get the updated object from the API
+    return context.dispatch('get', `${type}/${id}`)
+  }
+
   return {
     /**
      * Get items from the API
@@ -155,6 +201,45 @@ const actions = (api, conf) => {
         return related
       })
     },
+    /**
+     * DELETE an object's relationships via its `relationships URL`
+     *
+     * @async
+     * @memberof module:jsonapi-vuex.jsonapiModule.actions
+     * @param {object} context - Vuex context object
+     * @param {object} args - A restructured object, specifying relationship(s)  - e.g. `{ _jv: { type: "endpoint", id: "1", relationships: {...} } }`
+     * @param {object} args - A restructured object, specifying relationship(s)  - e.g. `{ _jv: { type: "endpoint", id: "1", relationships: {...} } }`
+     * @return {object} Restructured representation of the 'parent' item
+     */
+    deleteRelated: (context, args) => {
+      return writeRelated(context, args, 'delete')
+    },
+    /**
+     * PATCH an object's relationships via its `relationships URL`
+     *
+     * @async
+     * @memberof module:jsonapi-vuex.jsonapiModule.actions
+     * @param {object} context - Vuex context object
+     * @param {object} args - A restructured object, specifying relationship(s)  - e.g. `{ _jv: { type: "endpoint", id: "1", relationships: {...} } }`
+     * @param {object} args - A restructured object, specifying relationship(s)  - e.g. `{ _jv: { type: "endpoint", id: "1", relationships: {...} } }`
+     * @return {object} Restructured representation of the 'parent' item
+     */
+    patchRelated: async (context, args) => {
+      return writeRelated(context, args, 'patch')
+    },
+    /**
+     * POST to an object's relationships via its `relationships URL`
+     *
+     * @async
+     * @memberof module:jsonapi-vuex.jsonapiModule.actions
+     * @param {object} context - Vuex context object
+     * @param {object} args - A restructured object, specifying relationship(s)  - e.g. `{ _jv: { type: "endpoint", id: "1", relationships: {...} } }`
+     * @param {object} args - A restructured object, specifying relationship(s)  - e.g. `{ _jv: { type: "endpoint", id: "1", relationships: {...} } }`
+     * @return {object} Restructured representation of the 'parent' item
+     */
+    postRelated: async (context, args) => {
+      return writeRelated(context, args, 'post')
+    },
     /**
      * Post an item to the API
      *

tests/unit/actions/deleteRelated.spec.js

@@ -0,0 +1,80 @@
+import { expect } from 'chai'
+
+import createStubContext from '../stubs/context'
+import createJsonapiModule from '../utils/createJsonapiModule'
+import { jsonFormat as createJsonWidget1, normFormat as createNormWidget1 } from '../fixtures/widget1'
+
+describe('deleteRelated', function () {
+  let normWidget1, jsonWidget1, jsonapiModule, stubContext
+
+  beforeEach(function () {
+    normWidget1 = createNormWidget1()
+    jsonWidget1 = createJsonWidget1()
+
+    jsonapiModule = createJsonapiModule(this.api)
+    stubContext = createStubContext(jsonapiModule)
+  })
+
+  it('Should throw an error if passed an object with no type or id', async function () {
+    try {
+      await jsonapiModule.actions.deleteRelated(stubContext, { _jv: {} })
+      throw 'Should have thrown an error (no id)'
+    } catch (error) {
+      expect(error).to.equal('No type/id specified')
+    }
+  })
+
+  it('Should throw an error if passed an object with no relationships', async function () {
+    try {
+      await jsonapiModule.actions.deleteRelated(stubContext, { _jv: { type: 'widget', id: 1 } })
+      throw 'Should have thrown an error (no relationships)'
+    } catch (error) {
+      expect(error).to.equal('No relationships specified')
+    }
+  })
+
+  it('should make a delete request for the object passed in.', async function () {
+    this.mockApi.onDelete().replyOnce(204)
+    this.mockApi.onGet().replyOnce(200, { data: jsonWidget1 })
+
+    const rel = { data: { type: 'widget', id: '2' } }
+    normWidget1['_jv']['relationships'] = { widgets: rel }
+
+    await jsonapiModule.actions.deleteRelated(stubContext, normWidget1)
+    // Expect a delete call to rel url, with rel payload, then get object to update store
+    expect(this.mockApi.history.delete[0].url).to.equal('widget/1/relationships/widgets')
+    expect(this.mockApi.history.delete[0].data).to.deep.equal(JSON.stringify(rel))
+    expect(this.mockApi.history.get[0].url).to.equal('widget/1')
+  })
+
+  it('should handle multiple relationships', async function () {
+    this.mockApi.onDelete().reply(204)
+    this.mockApi.onGet().replyOnce(200, { data: jsonWidget1 })
+
+    const rel1 = { data: { type: 'widget', id: '2' } }
+    const rel2 = { data: { type: 'doohickey', id: '3' } }
+    normWidget1['_jv']['relationships'] = { widgets: rel1, doohickeys: rel2 }
+
+    await jsonapiModule.actions.deleteRelated(stubContext, normWidget1)
+    expect(this.mockApi.history.delete[0].url).to.equal('widget/1/relationships/widgets')
+    expect(this.mockApi.history.delete[0].data).to.deep.equal(JSON.stringify(rel1))
+    expect(this.mockApi.history.delete[1].url).to.equal('widget/1/relationships/doohickeys')
+    expect(this.mockApi.history.delete[1].data).to.deep.equal(JSON.stringify(rel2))
+    expect(this.mockApi.history.get[0].url).to.equal('widget/1')
+    // Only get the object once at end
+    expect(this.mockApi.history.get.length).to.equal(1)
+  })
+
+  it('Should handle API errors (in the data)', async function () {
+    this.mockApi.onDelete().reply(500)
+
+    const rel = { data: { type: 'widget', id: '2' } }
+    normWidget1['_jv']['relationships'] = { widgets: rel }
+
+    try {
+      await jsonapiModule.actions.deleteRelated(stubContext, normWidget1)
+    } catch (error) {
+      expect(error.response.status).to.equal(500)
+    }
+  })
+})

tests/unit/actions/patchRelated.spec.js

@@ -0,0 +1,80 @@
+import { expect } from 'chai'
+
+import createStubContext from '../stubs/context'
+import createJsonapiModule from '../utils/createJsonapiModule'
+import { jsonFormat as createJsonWidget1, normFormat as createNormWidget1 } from '../fixtures/widget1'
+
+describe('patchRelated', function () {
+  let normWidget1, jsonWidget1, jsonapiModule, stubContext
+
+  beforeEach(function () {
+    normWidget1 = createNormWidget1()
+    jsonWidget1 = createJsonWidget1()
+
+    jsonapiModule = createJsonapiModule(this.api)
+    stubContext = createStubContext(jsonapiModule)
+  })
+
+  it('Should throw an error if passed an object with no type or id', async function () {
+    try {
+      await jsonapiModule.actions.patchRelated(stubContext, { _jv: {} })
+      throw 'Should have thrown an error (no id)'
+    } catch (error) {
+      expect(error).to.equal('No type/id specified')
+    }
+  })
+
+  it('Should throw an error if passed an object with no relationships', async function () {
+    try {
+      await jsonapiModule.actions.patchRelated(stubContext, { _jv: { type: 'widget', id: 1 } })
+      throw 'Should have thrown an error (no relationships)'
+    } catch (error) {
+      expect(error).to.equal('No relationships specified')
+    }
+  })
+
+  it('should make a patch request for the object passed in.', async function () {
+    this.mockApi.onPatch().replyOnce(204)
+    this.mockApi.onGet().replyOnce(200, { data: jsonWidget1 })
+
+    const rel = { data: { type: 'widget', id: '2' } }
+    normWidget1['_jv']['relationships'] = { widgets: rel }
+
+    await jsonapiModule.actions.patchRelated(stubContext, normWidget1)
+    // Expect a patch call to rel url, with rel payload, then get object to update store
+    expect(this.mockApi.history.patch[0].url).to.equal('widget/1/relationships/widgets')
+    expect(this.mockApi.history.patch[0].data).to.deep.equal(JSON.stringify(rel))
+    expect(this.mockApi.history.get[0].url).to.equal('widget/1')
+  })
+
+  it('should handle multiple relationships', async function () {
+    this.mockApi.onPatch().reply(204)
+    this.mockApi.onGet().replyOnce(200, { data: jsonWidget1 })
+
+    const rel1 = { data: { type: 'widget', id: '2' } }
+    const rel2 = { data: { type: 'doohickey', id: '3' } }
+    normWidget1['_jv']['relationships'] = { widgets: rel1, doohickeys: rel2 }
+
+    await jsonapiModule.actions.patchRelated(stubContext, normWidget1)
+    expect(this.mockApi.history.patch[0].url).to.equal('widget/1/relationships/widgets')
+    expect(this.mockApi.history.patch[0].data).to.deep.equal(JSON.stringify(rel1))
+    expect(this.mockApi.history.patch[1].url).to.equal('widget/1/relationships/doohickeys')
+    expect(this.mockApi.history.patch[1].data).to.deep.equal(JSON.stringify(rel2))
+    expect(this.mockApi.history.get[0].url).to.equal('widget/1')
+    // Only get the object once at end
+    expect(this.mockApi.history.get.length).to.equal(1)
+  })
+
+  it('Should handle API errors (in the data)', async function () {
+    this.mockApi.onPatch().reply(500)
+
+    const rel = { data: { type: 'widget', id: '2' } }
+    normWidget1['_jv']['relationships'] = { widgets: rel }
+
+    try {
+      await jsonapiModule.actions.patchRelated(stubContext, normWidget1)
+    } catch (error) {
+      expect(error.response.status).to.equal(500)
+    }
+  })
+})