Add custom actions and so much more

Author: kiaking

docs/.vuepress/config.js

@@ -5,10 +5,10 @@ const sidebars = {
       collapsable: false,
       children: [
         '/guide/installation',
-        '/guide/getting-started',
-        '/guide/basic-usage',
-        '/guide/advanced-usage',
+        '/guide/setup',
+        '/guide/usage',
         '/guide/configurations',
+        '/guide/custom-actions',
         '/guide/sponsors'
       ]
     },

docs/api/request.md

@@ -75,9 +75,3 @@ User.api().get()
 - **`delete(url: string, config: Config = {}): Promise<Response>`**
 
   Performs a `DELETE` request. It takes the same argument as Axios's `delete` method.
-
-### fetch
-
-- **`fetch(url: string, params: any, config: Config = {}): Promise<Response>`**
-
-  The `fetch` method works almost as same as `get` method, but it will take URL query parameters as the 2nd argument. Please [refer here](../guide/advanced-usage.html#fetch) for more details.

docs/guide/advanced-usage.md

@@ -15,7 +15,7 @@ import VuexORMAxios from '@vuex-orm/plugin-axios'
 
 VuexORM.use(VuexORMAxios, {
   axios,
-  headers: {'X-Requested-With': 'XMLHttpRequest'},
+  headers: { 'X-Requested-With': 'XMLHttpRequest' },
   baseURL: 'https://example.com/api/'
 })
 ```
@@ -36,7 +36,7 @@ class User extends Model {
   }
 
   static apiConfig = {
-    headers: {'X-Requested-With': 'XMLHttpRequest'},
+    headers: { 'X-Requested-With': 'XMLHttpRequest' },
     baseURL: 'https://example.com/api/'
   }
 }
@@ -46,7 +46,7 @@ Finally, you can pass configuration when making the api call.
 
 ```js
 User.api().get('/api/users', {
-  headers: {'X-Requested-With': 'XMLHttpRequest'},
+  headers: { 'X-Requested-With': 'XMLHttpRequest' },
   baseURL: 'https://example.com/api/'
 })
 ```
@@ -59,7 +59,9 @@ All Axios configurations are available. For those, please refer to [the Axios do
 
 ### dataKey
 
-- **`dataKey: string | null`**
+- **`dataKey?: string | null`**
+
+  This option will define which key to look for when persisting response data. Let's say your response from the server looks like below.
 
   ```js
   {
@@ -82,3 +84,37 @@ All Axios configurations are available. For those, please refer to [the Axios do
   ```
 
   With the above config, the data inside `data` key will be inserted to the store.
+
+### save
+
+- **`save: boolean = true`**
+
+  This option will determine whether to store the response data to the store or not. If you set this value to `false`, the response data will not be persisted to the store. In that case, the `entities` property at the Response object will become null.
+
+  ```js
+  User.api().get('/api/users', {
+    save: false
+  })
+  ```
+
+### delete
+
+- **`delete?: string | number | (model: Model) => boolean`**
+
+  When this option is defined, the matching record will be deleted from the store after the api call. Usually, you need to set this when calling api to delete a record. When this option is set, the response data will not be persisted even if the `save` option is set to true.
+
+  ```js
+  User.api().delete('/api/users', {
+    delete: 1
+  })
+  ```
+
+  Well, you may wonder having to manually specify what record to be deleted is a bit redundant. However, without this option, Vuex ORM Axios wouldn't know what records should be deleted because it can't rely on the response data.
+
+  We're open to any suggestions and recommendations to improve the "delete" functionality. Please feel free to open an issue on GitHub!
+
+### actions
+
+- **`actions?: { [name: string]: ActionObject | ActionFunction }`**
+
+  You can define custom actions in here. Please refer to the [Custom Actions](custom-actions) page to learn more about it.

docs/guide/configurations.md

@@ -0,0 +1,88 @@
+# Custom Actions
+
+The Custom Actions lets you define your own predefined api methods. You can define any number of custom actions through your Model configurations through `actions` option.
+
+```js
+class User extends Model {
+  static entity = 'users'
+
+  static fields () {
+    return {
+      id: this.attr(null),
+      name: this.attr('')
+    }
+  }
+
+  static apiConfig = {
+    actions: {
+      fetch: {
+        method: 'get',
+        url: '/api/users'
+      }
+    }
+  }
+}
+```
+
+You can see that in the above example, we have defined `fetch` action with the option that defines the `method` and `url`.
+
+Now you may call this action as if it was a predefined method.
+
+```js
+User.api().fetch()
+```
+
+The above method will perform api call to `/api/users` with `GET` method. Now the value for the action (in the example, which is the object that defines `method` and `url`) is the request configuration. Now you see that the above example is equivalent to calling:
+
+```js
+User.api().request({
+  method: 'get',
+  url: '/api/users'
+})
+```
+
+Actions can also be defined as a function. In this case, just call the desired method with in action. With this approach, you can configure the convenience argument to the action, and gives you more powerful control.
+
+Remember that inside the function, `this` is bind to the Request object, not the Model where the actions are defined.
+
+```js
+class User extends Model {
+  static apiConfig = {
+    actions: {
+      fetchById (id) {
+        return this.get(`/api/users/${id}`)
+      }
+    }
+  }
+}
+```
+
+And you can call that action like so.
+
+```js
+User.api().fetchById(1)
+```
+
+## When to Use Custom Actions?
+
+While the custom actions are convenient and easy to set up, you can always define methods to the Model directly to get pretty much the same result.
+
+```js
+class User extends Model {
+  static fetchById (id) {
+    return this.api().get(`/api/users/${id}`)
+  }
+}
+```
+
+Well of crouse in this case, you must call that method from Model and not from `api()` method.
+
+```js
+User.fetchById(1)
+```
+
+To be honest, this is a much better way to define custom methods in terms of simplicity and also better with type safety when using TypeScript.
+
+The benefits of defining custom actions inside the configuration are that you can put those methods under Request object, so it becomes more consistent when calling it from the Model. Also, it could be easier to share custom actions between different Models.
+
+It's up to you how to define custom actions. Though if you have any ideas or feedback, we're more than happy to hear it from you!

docs/guide/custom-actions.md

@@ -1,8 +1,6 @@
 # Setup
 
-This page is a quick start guide to begin using Vuex ORM. It assumes you have a basic understanding of Vuex ORM. If you are not familiar with Vuex ORM, please check out the [Vuex ORM Documentation](https://vuex-orm.github.io/vuex-orm/).
-
-At first, Vuex ORM Axios requires manually passing Axios instance during the installation process. Please make sure you have axios installed to your app.
+At first, Vuex ORM Axios requires manually passing Axios instance during the setup process. Please make sure you have axios installed to your app.
 
 To install Vuex ORM Axios to Vuex ORM, pass Vuex ORM Axios to the `VuexORM.use` method. Here, you should pass your axios instance as an option.
 

docs/guide/getting-started.md renamed to docs/guide/setup.md

@@ -1,4 +1,4 @@
-# Basic Usage
+# Usage
 
 After setting up Vuex ORM Axios, you may use `Model.api` method to perform api call.
 
@@ -61,6 +61,18 @@ User.api().get('users', {
 
 There're additional configuration specific to Vuex ORM Axios as well. Please check out [Configurations page](configurations) for more.
 
+### Note on Delete Method
+
+Even when you call `delete` method, it will not delete records from the store. It just means that it will perform HTTP DELETE request. If you want to delete the record after calling the API, you must define `delete` option.
+
+```js
+User.api().delete('/api/users/1', {
+  delete: 1
+})
+```
+
+The above example will delete the user record with an id of 1. Please check out [Configurations page](configurations) for more.
+
 ## Response
 
 The response object is a bit different from Axios response and contains 2 properties. One is `response`, which is the pure Axios response object, and the second one is the `entities`, which holds Vuex ORM persistent result.

docs/guide/basic-usage.md renamed to docs/guide/usage.md

@@ -1,6 +1,5 @@
 import { AxiosInstance, AxiosResponse } from 'axios'
 import { Model } from '@vuex-orm/core'
-import GlobalConfig from '../contracts/GlobalConfig'
 import Config from '../contracts/Config'
 import Response from './Response'
 
@@ -10,13 +9,27 @@ export default class Request {
    */
   model: typeof Model
 
+  /**
+   * The default config.
+   */
+  config: Config = {
+    save: true
+  }
+
   /**
    * Create a new api instance.
    */
   constructor (model: typeof Model) {
     this.model = model
+
+    this.registerActions()
   }
 
+  /**
+   * Index key for the user defined actions.
+   */
+  [action: string]: any
+
   /**
    * Get the axios client.
    */
@@ -28,6 +41,41 @@ export default class Request {
     return this.model.axios
   }
 
+  /**
+   * Register actions from the model config.
+   */
+  private registerActions (): void {
+    const actions = this.model.apiConfig.actions
+
+    if (!actions) {
+      return
+    }
+
+    for (const name in actions) {
+      const action = actions[name]
+
+      typeof action === 'function'
+        ? this.registerFunctionAction(name, action)
+        : this.registerObjectAction(name, action)
+    }
+  }
+
+  /**
+   * Register the given object action.
+   */
+  private registerObjectAction (name: string, action: any): void {
+    this[name] = (config: Config) => {
+      return this.request({ ...action, ...config })
+    }
+  }
+
+  /**
+   * Register the given function action.
+   */
+  private registerFunctionAction (name: string, action: any): void {
+    this[name] = action.bind(this)
+  }
+
   /**
    * Perform a get request.
    */
@@ -63,13 +111,6 @@ export default class Request {
     return this.request({ method: 'delete', url, ...config })
   }
 
-  /**
-   * Fetch data from the api.
-   */
-  fetch (url: string, params: any = {}, config: Config = {}): Promise<Response> {
-    return this.get(url, { params, ...config })
-  }
-
   /**
    * Perform an api request.
    */
@@ -78,22 +119,39 @@ export default class Request {
 
     const response = await this.axios.request(requestConfig)
 
-    const entities = await this.model.insertOrUpdate({
-      data: this.getDataFromResponse(response, requestConfig)
-    })
+    const entities = await this.persistResponseData(response, requestConfig)
 
-    return new Response(response, entities)
+    return new Response(this.model, requestConfig, response, entities)
   }
 
   /**
    * Create a new config by merging the global config, the model config,
    * and the given config.
    */
   private createConfig (config: Config): Config {
-    const globalConfig: GlobalConfig = this.model.globalApiConfig
-    const modelConfig: Config = this.model.apiConfig || {}
+    return {
+      ...this.config,
+      ...this.model.globalApiConfig,
+      ...this.model.apiConfig,
+      ...config
+    }
+  }
+
+  /**
+   * Persist the response data to the vuex store.
+   */
+  private async persistResponseData (response: AxiosResponse, config: Config): Promise<any> {
+    if (!config.save) {
+      return null
+    }
 
-    return { ...globalConfig, ...modelConfig, ...config }
+    if (config.delete !== undefined) {
+      return this.model.delete(config.delete as any)
+    }
+
+    return this.model.insertOrUpdate({
+      data: this.getDataFromResponse(response, config)
+    })
   }
 
   /**