@crishellco/vue-call-store

v3.1.24

Published

2 months ago

A Vuex module and Vue mixin to track the status of all API calls

Downloads

493

0High
0Medium
0Low

crishellco

Vue Call Store

A Vue & Vuex plugin to simplify tracking API call statuses.

Vue Call Store provides a Vuex module and component methods to make it easy to update API call statuses and keep track of them.

Check out the demo

Install

yarn add -D @crishellco/vue-call-store
yarn add -D vuex
# or
npm i -D @crishellco/vue-call-store
npm i -D vuex

import Vuex from 'vuex';
import VueCallStore from '@crishellco/vue-call-store';

/**
 * If Vuex isn't installed,
 * it will be installed.
 */
Vue.use(Vuex);

const store = new Vuex.Store({});

Vue.use(VueCallStore, { store, minDuration: 2000 });

Install Options

| Name | Type | Default | Description | |-------------------|-----------|----------------------|--------------------------------------------------------------------------------| | disablePromises | Boolean | false | Disables promises when updating a call. Useful for tests. | | minDuration | Number | 0 | The minimum time in milliseconds that all requests must take before finishing. | | store | Vuex | new Vuex.Store({}) | A Vuex store to store request data. |

Examples

Update the status of a call

/**
 * @arg {string} identifier
 * @arg {*} [message]
 */
vm.$calls.start('fetchUsers');
vm.$calls.end('fetchUsers');
vm.$calls.fail('fetchUsers', error);

// Example usage in a Vuex action
new Vuex.Store({
  actions: {
    fetchUsers({ commit, dispatch }) {
      const identifier = 'fetchUsers';

      dispatch('calls/start', { identifier });

      axios
        .get('/api/users')
        .then(({data} => {
          commit('users/set', data);
          dispatch('calls/end', { identifier });
        })
        .catch(({response}) => {
          dispatch('calls/fail', { identifier, message: response.data.errors });
        });
    },
  },
});

Check the status of a call in a component

/**
 * @arg {string | array} identifier
 * @returns {boolean}
 */

const isPending = vm.$calls.isPending('fetchUsers');
const isDone = vm.$calls.isDone('fetchUsers');
const hasFailed = vm.$calls.hasFailed(['fetchUsers', 'second']);

Conditionally render with directives

Directives accept string or array of identifiers.

<template>
  <loading-indicator v-call:pending="'fetchUsers'" />

  <div v-call:done="'fetchUsers'" class="content">
    <ul>
      <li v-for="user in users" :key="user.id">{{ user.name }}</li>
    </ul>
  </div>

  <div v-call:failed="['fetchUsers', 'second']" class="content">
    Oops! Unable to fetch users.
  </div>

Conditionally render with components

Components' identifier props accept string or array of identifiers.

Components' once props accept a boolean. When true, the slot contents will only be hidden once.

  <v-call-pending identifier="fetchUsers" :once="true">
    <loading-indicator />
  </v-call-pending>

  <v-call-failed identifier="fetchUsers">
    <div class="content">
      <ul>
        <li v-for="user in users" :key="user.id">{{ user.name }}</li>
      </ul>
    </div>
  </v-call-failed>

  <v-call-failed :identifier="['fetchUsers', 'second']">
    <div class="content">
      Oops! Unable to fetch users.
    </div>
  </v-call-failed>
</template>

Multiple identifer logic

| State | Method | to be true | |---------|-------------------------------------|---------------------------------| | pending | $callIsPending | $calls.isPending | at least one of many is pending | | done | $callIsDone | $calls.isDone | all are done | | failed | $callHasFailed | $calls.hasFailed | has least one has failed |

See Source

Get the raw call object

/**
 * @arg {string} identifier
 * @arg {*} [defaultValue = null]
 * @returns {object|null}
 */
const notFoundValue = { status: 'done' };
const call = vm.$calls.get('fetchUsers', notFoundValue);

// Format
{
  _duration: 200, // milliseconds
  _started: moment('2019-04-02T15:19:05.000'), // or null
  _stopped: moment('2019-04-02T15:19:05.200'), // or null
  message: 'message',
  status: 'done',
}

Available actions & mutations

dispatch('calls/start', { identifier, message });
dispatch('calls/end', { identifier, message, minDuration });
dispatch('calls/fail', { identifier, message, minDuration });
commit('calls/RESET'); // Removes all call objects

Api

vm.$calls.end(identifier, message)

vm.$endCall(identifier, message)

Ends a call.

Arguments
- {string} identifier
- {*} message optional
Returns {void}

vm.$calls.fail(identifier, message)

vm.$failCall(identifier, message)

Fails a call.

Arguments
- {string} identifier
- {*} message optional
Returns {void}

vm.$calls.start(identifier, message)

vm.$startCall(identifier, message)

Starts a call.

Arguments
- {string} identifier
- {*} message optional
Returns {void}

vm.$getCall(identifier, defaultValue)

vm.$calls.get(identifier, defaultValue)

Gets raw call.

Arguments
- {string} identifier
- {*} defaultValue (default: null) optional
Returns {object}

vm.$calls.hasFailed(identifier)

vm.$callHasFailed(identifier)

Gets if one or at least one of many calls has failed.

Arguments
- {string | array} identifier
Returns {boolean}

vm.$calls.isDone(identifier)

vm.$callIsDone(identifier)

Gets if one or all calls are done.

Arguments
- {string} identifier
Returns {boolean}

vm.$calls.isPending(identifier)

vm.$callIsPending(identifier)

Gets if one or at least one of many calls is pending.

Arguments
- {string} identifier
Returns {boolean}

Development

Test

yarn test

Build

yarn build