Vue Chimera

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

View demo Download Source

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
Bash

Using bower:

$ bower install vue-chimera
Bash

Using cdn:

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

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)
JavaScript

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 { ... }
  }
  
})
JavaScript

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
      }
    }
    
})
JavaScript

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>
HTML

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
      })
    
    }
    
  }

})
JavaScript

Resource properties and methods

Property Type Default Value Description
data Object/ Array null The resource response object or string returned from server when request is successfull
loading Boolean false Indentifies the resource is in loading state
error Object/string null Error json object or string returned from server when request failed
lastLoaded Date null The date/time from last time resource successfully loaded (null if not loaded yet)
status number null Resource response status
headers Object null Resource response/error headers
Method Return type Description
reload(force) Promise Fetches the resource from server. force: True for cache busting
execute(force) Promise Same as Reload
on(event, handler) Sets an event listener. Events
cancel() void Interupts request

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}`
      }
    }

})
JavaScript

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
      
    }
  }
...
JavaScript

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
          }
        }
      }
    }
  }
  
})
JavaScript

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)
        })
      }
    }
    
})
JavaScript

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
  }
  
}
JavaScript

You can also disable SSR for some heavy resources

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

GitHub

chimera-js/vue-chimera

??

— Read More

Download as zip