VueJS RESTful client with reactive resources and endpoints

Vue Chimera

VueJS RESTful client with reactive features. Vue-Chimera is based on axios http client library.

Overview of features:

• Reactive endpoints and requests based on vue instance data
• Loading flags
• Get time when the resource was latestly loaded
• Set interval time to refresh data on an endpoint
• Simple robust resource definition
• Nuxtjs compatible with Server side prefetching
• Simple cancelation on requests
• Cancel all pending requests on vue instance destroy
• Events and handlings
• Lightweight

Installing

Using npm:

$ npm install vue-chimera

Using bower:

$ bower install vue-chimera

Using cdn:

<script src="https://unpkg.com/vue-chimera@latest/dist/vue-chimera.js"></script>

Getting started

To add vue-chimera to your Vue you must use it as a plugin:
ECMAScript 6

import Vue from 'vue'
import VueChimera from 'vue-chimera'

Vue.use(VueChimera)

If you use old browser style just add vue.min.js and dist/vue-chimera.js script tag to your HTML file and everything would be fine to go on.

Defining Resources

To use Vue Chimera in your vue instance you should add chimera property to root of your vue component instance:

let app = new Vue({
  
  // Chimera property contains all of chimera restful queries/resources and options
  chimera: {
    
    // Here you can define your restful resources and api endpoints
    resources: {
      mySampleResource: '/users'
    }
  },
  
  data() {
    return { ... }
  }
  
})

Vue Chimera automatically converts your resources to Resource Object
Your resources can be:

• A simple string for simple GET requests
• An Object for complex resources like: POST, PATCH, with Parameters, with Headers, Response/Error transformer, Event listeners
• An instance of Resource
• A Function for reactive resources Reactive-Resources

var app = new Vue({
    
    chimera: {
      
      // You can use axios config to set default config for your axios http client library
      axios: {
        baseURL: 'https://my-domain.com/api/v1',
        headers: {
          'X-Sample-Access-Token': 'xxx'
        }
      },
      
      // Or you can directly pass a axios client for more control over your client
      axios: axios.create(),
      
      resources: {
      
        users: '/users',
        
        time: {
          'url': '/time',
          // With interval option set to 5000, resource will be refreshed every 5000 miliseconds
          'interval': 5000
        },
        
        // a sample POST request
        sendPost: {
          url: '/posts',
          method: 'POST',
          params: {
            title: 'Sample',
            body: '<h1>Vue Chimera is awesome...</h1>'
          },
          
          // Set prefetch to false to prevent request from sending on application load.
          prefetch: false
        }
        
      }
      
    },
    
    data() {
      return {
        selectedUserID: 1
      }
    }
    
})

Now it's time to use our resources in our vue template or inside vue methods.

Use Resources in template

chimera instance can be accessed in templates with $chimera (Dollar sign prepended) or you can get resources by simply type it's name, It had been injected in computed properties by the plugin.
data is the final json result of our restful resource
loading is a boolean flag, identifies the resource is loading.
You can read other resource property and methods here.

<template>
  <div>
    <!-- `users` is Resource object defined in chimera (same as: `$chimera.users`) -->
    <ul v-if="users.data && !users.loading">
      <li v-for="user in users.data">
        {{ user.name }}
      </li>
    </ul>
    <small v-else>Loading...</small>
  </div>
</template>

Use Resources in script

You can simply access chimera instance with $chimera

let app = new Vue({
  
  methods: {
    
    sendUser() {
      
      // Execute function on resources, sends the request and returns a Promise
      this.$chimera.sendUser.execute().then(res => {
          
          // You can do other things after request success here.
          
      }).catch(err => {
          // Or error handlings
      })
    
    }
    
  }

})

Resource properties and methods

Reactive Resources

You can also set a function to a resource that will return String, Object, instance of Resource same as before,
to let your resources be reactive and change.

let app = new Vue({

    data() {
      return {
        selectedUserId: 1,
        postId: 2
      }
    },

    chimera: {
      resources: {
        
        post() {
          return {
            url: '/api/v1/posts',
            params: {
              postId: this.postId
            },
            method: 'post',
            prefetch: true
          }
        },
        
        user: () => `/api/v1/users/${this.selectedUserId}`
      }
    }

})

Note that prefetch evaluates to false, your data will be reactive and change but won't be fetched until you call the reload function of the resource

Chimera instance properties

...
  methods: {
    send() {
      
      // Global identifier to check if any request is pending
      this.$chimera.$loading
      
      // Get the axios client to modify or ...
      this.$chimera.$axios
      
    }
  }
...

Transformers

Transformers is used to change the response to another format. It would be called before the request response (error or success) is mapped to the data attribute of Resource object.

new Vue({
  
  chimera: {
    resources: {
      users: {
        
        url: '/users',
        
        transformers: {
          response: (response) => {
            if (response.user)
              response.user.id = 'UID: ' + response.user.id
            return response
          },
          error: (error) => {
            error.msg = error.msg || 'Something went wrong'
            return error
          }
        }
      }
    }
  }
  
})

Events

import { EVENT_SUCCESS, EVENT_ERROR, EVENT_LOADING, EVENT_CANCEL } from 'vue-chimera/src/Resource.js'

new Vue({

    chimera: {
      resources: {
        users: {
          url: '/users',
          on: {
            [EVENT_CANCEL]: (resource) => {
                // Calls when a request interrupted and cancelled
            }
          }
        }
      }
    },
    
    methods: {
      // Or listen programmatically
      listenToError() {
        this.$chimera.users.on(EVENT_ERROR, function(err) {
          alert('Oops error occured! status: ' + err.status)
        })
      }
    }
    
})

Using with Nuxt.js

You can use Vue-Chimera with nuxtjs to use it's SSR features so you can easily prefetch the data.

// nuxt.config.js

module.exports = {
  
  modules: [
    'vue-chimera/nuxt'
  ],
  
  chimera: {
    // Server side prefetch will only be available for resources that has `prefetch` and `ssrPrefetch`
    prefetch: 'get',
    
    // Enables server side prefetch on resources
    // true: fetched on server
    // false: fetched on client
    // 'override': fetched on server and client (overrided by client)
    ssrPrefetch: true,
    
    ssrPrefetchTimeout: 2000 // Server side timeout for prefetch
  }
  
}

You can also disable SSR for some heavy resources

...
    resources: {
      myResource: {
        url: '/api/v1/example',
        ssrPrefetch: false // Prefetch disabled on a specific resource
      }
    }
...

GitHub