README.md

v-cache

The source code for v-cache a VueJS Directive.

About

What is v-cache?

v-cache is a VueJS directive that can be used on any custom VueJS Component. It gives the custom component the ability to cache data, restore data from cache, and clear its cache data by emitting one of three simple VueJS events:

• $emit('cache')
• $emit('cache-restore')
• $emit('cache-clear')

When and why should I use v-cache?

Have you ever been filling out a long form and accidentally navigated away? Or had your browser crash? Or your computer start updates? Normally, all of that work would be lost. With v-cache, revisiting the page will cause in-progress data to be restored to your custom component. Because the data is stored locally, this works even if your computer loses access to the internet.

Advantages:

• No database required
• Incredibly fast
• Works even when internet goes out
  • Or for offline web apps!
• Survives page refreshes, new tabs, and even PC restarts

Cons:

• Does not persist across multiple devices
• Employ caution when caching sensative information

Notes:

• If data is not cleared, it will persist to additional tabs and potentially across multiple user sessions
• Data is tied to the MACHINE, not necessarily the logged in user
• Scoped to the domain the data is cached on

Installation

// NPM
npm install v-cache --save

// Yarn
yarn add v-cache

main.js

import Vue from 'vue';
import vCache from 'v-cache';

Vue.directive("cache", vCache);

Basic Usage

App.vue

<template>
  <div id="app">
    
    <!-- Where the magic happens -->
    <custom-form v-cache="'unique-key'" />

  </div>
</template>

<script>
import CustomForm from "./components/CustomForm.vue"

export default {
  name: "app",
  components: {
    CustomForm
  }
}
</script>

/components/CustomForm.vue

<template><!-- Business as usual --></template>

<script>
export default {
  name: 'CustomForm',
  data() {
    return {
      form: { /* misc fields */ }
    }
  },
  watch: {
    // Watch for changes to all of form's properties
    // and trigger caching behavior
    form: {
      handler: function() {
        this.$emit("cache", this.form);
      },
      deep: true
    }
  },
  mounted() {
    // After this form is rendered, restore its form values
    // if it has any cached form values
    this.$emit("restore-cache");
  },
  methods: {
    submit() {
      // Clear any cached values for this form
      this.$emit("clear-cache");
    }
  }
}
</script>

Advanced Usage

v-cache can accept either a single string to set the key used to store/retrieve data, or an object that allows you to override default behavior for the directive. Examples for both are included below. You can see the default values for each of the properties in src/index.js.

// Simple
<my-custom-form-component v-cache="'my-unique-key'" />


// All Available Options
<my-custom-form-component
    v-cache="{
        /* Required, the unique key we use to cache
        * the component's data w/ localforage
        */
        key: 'my-unique-key',

        /* The property to "cache" data from.
        * When NULL, cache all component data
        */
        cacheTarget: 'form',
        
        /* The property to "restore" data from cache to.
        * When NULL, merge against all component data
        */
        restoreTarget: 'form',

        /* Handles a successful restore. Has access to the
        * value found in cache, the Vuejs virtual node for
        * the custom component, and the restoreTarget (string)
        */
        successHandler: (value, vnode, restoreTarget) => {},

        /* Called if localforage fails when attempting to
        * cache or restore cache. localforage's error object
        */
        errorHandler: (err) => {},

        /* Called _after_ a successful restore. Provides
        * access to the raw value retrieved from the cache.
        */
        restoreCallback: (value) => {}
    }"
/>

Attaching the v-cache directive to a custom component wires it up to use caching functionality. To leverage this functionality, you can $emit one of the following events from inside the component:

Event	Behavior	Options (optional)
$emit('cache')	save cacheTarget to cache	$emit('cache', /* data to cache */)
$emit('cache-restore')	restore cache to restoreTarget	$emit('cache-restore', 'new-restore-target') OR $emit('cache-restore({ restoreTarget: '', successHandler: ()=> {}, errorHandler: () => {} })
$emit('cache-clear')	clear cache	N/A

Roadmap

v2

• Config option to not cache password fields
• Ability to cache native forms and form elements directly

LICENSE

MIT