vue-raii

Resource acquisition is initialization. -Bjarne Stroustrup

Why, yes, I'm bringing a C++ idiom to Vue.js. This Vue plugin allows you to bind JavaScript resources to the lifetime of a component. Basically, if you:

• need to register a function somewhere and then have to deregister it.
• have an object where you have to call open to use it and then call close when you're done with it
• guarantee that a resource is destroyed before another

Then this plugin has you covered. It lets you define constructors and destructors such that:

• Constructors run after each other in the order they were registered and destructors run in reverse order when the component is destroyed.
• When constructors return promises, destructors are only run after promises have fulfilled. This plugin was made with async in mind.
• Resources can be created at any point. You can create them in any method you like. Want to establish a connection to a socket? Call a method that creates the resource.
• Resources can also be destroyed at any point. Destructors for manually destroyed resources will not run again when the component gets destroyed.

Unit tests are run through versions 2.0 to 2.6 of Vue.js

Examples

Run npm run examples to see fully functional examples locally on your browser. There's a clock, an echo chamber and a dude that won't stop staring at your mouse. Quite persuasive, if you ask me!

Here are just a few small examples:

Using setInterval and clearInterval:

{
  data() {
    this.$raii(
      {
        constructor: () => setInterval(this.updateTime, 1000),
        destructor: (resource) => clearInterval(resource),
      });

    return {
      time: new Date()
    };
  },

  methods: {
    updateTime() {
      this.time = new Date();
    }
  }
}

Listening to native DOM events:

{
  data() {
    this.$raii(
      {
        constructor: () => document.addEventListener('mousemove', this.updatePosition),
        destructor: () => document.removeEventListener('mousemove', this.updatePosition),
      });

    return {
      position: {
        x: 0,
        y: 0
      }
    };
  },

  methods: {
    updatePosition(e) {
      this.position.x = e.pageX;
      this.position.y = e.pageY;
    }
  }
}

Sockets:

{
  data() {
    this.$raii({
      // Allows you to get a reference to the resource later on.
      id: 'socket',

      // Constructor. Can return a promise.
      constructor: () => new Promise((resolve, reject) => {
        let socket = new WebSocket('ws://localhost:8080');

        socket.addEventListener('open', () => resolve(socket));
        socket.addEventListener('error', reject);
      }),

      // Destructor. It is only called if promise resolves successfully.
      destructor: (socket) => socket.close()
    });

    return {
      message: '',
    };
  },

  methods: {
    async sendMessage() {
      // Reference resource. Promise fulfills when constructor finishes running.
      let socket = await this.$raii('socket');

      socket.send(this.message);
    }
  }
}

Install

npm install vue-raii

Usage

Require the vue-raii module and pass it to Vue.use.

const VueRaii = require('vue-raii')

Vue.use(VueRaii)

You will then have access to the $raii method in every Vue component.

Documentation

Creating resources

Resources are created by passing an object to the $raii method. The call will return a promise that gets resolved when the resource is constructed and ready to use.

Property | Description ------------|------------------------------------------------- id | (optional) resource identifier. Must be a string and uniquely identify the resource. Necessary if you want to reference the resource later on. constructor | A function that is called to construct the resource. It must return the resource. destructor | (optional) A function that is called to destroy the resource.

Example:

await this.$raii({
  id: 'timer',
  constructor: () => setInterval(this.updateTime, 1000),
  destructor: (resource) => clearInterval(resource),
});

Retrieving resources

Pass the id as the only argument to the $raii method. The call will return a promise that gets resolved to the resource.

You can call this right after you register the resource. The promise will resolve once the resource is constructed.

Example:

await this.$raii('timer');

Manually destroying resources

Pass a string that identifies the resource and the string "destroy" to the $raii method. It will return a promise that gets resolved when the resource is destroyed.

Example:

await this.$raii('timer', 'destroy');

Contributing

The easiest way to contribute is by starring this project on GitHub!

https://github.com/daniel-araujo/vue-raii

If you've found a bug, would like to suggest a feature or need help, feel free to open issues on GitHub:

https://github.com/daniel-araujo/vue-raii/issues