volante

6.10.0 • Public • Published

volante

Volante is a lightweight framework for a hub-and-spoke pattern. It organizes your modules into coherent objects and then provides lots of built-in goodies to make it easier to create your app.

Features

  • structured JSON config file to control the entire wheel and individual modules
  • environment variable overrides to config file for changes at run-time
  • automatic volante module discovery (found using 'volante' npm keyword)
  • built-in logging methods (logging output delegated to volante spoke modules)
  • built-in status tracking for modules
  • structured event handling
  • ability to register for wildcard events ('*')

volante.Hub

The volante.Hub may be extended or instanced directly. The public volante.Hub methods are typically used to perform final stitching/configuration as shown below.

const volante = require('volante');

let hub = new volante.Hub().attachAll(); // attachAll automatically finds all local Volante modules

hub.loadConfig('config.json'); // load a config file

// the hub can act on any volante event here
hub.on('VolanteExpress.listening', () => {
  console.log('my server is running')
});

Config file format

The config file should be a JSON file and may have the following top level fields which affect Volante config:

  • name - set the Hub name, effectively setting the name for the entire service
  • debug - global debug mode flag
  • attach - array of module npm module names to attach from node_modules
  • attachLocal - array of local modules to attach

Additionally, the fields of any top-level object names matching a Volante spoke name will be loaded as that spoke's props. For example, if the config file contains:

{
  "VolanteExpress": {
    "bind": "0.0.0.0",
    "port": 3000,
  }
}

the Volante hub will set the bind and port properties of VolanteExpress at startup (pre-init).

Environment variable override

For the above example config, you can define volante_VolanteExpress_port=8080 to override the port value. Everything after the volante_ prefix is case-sensitive, to ensure a positive match in the config file.

Data members provided by volante.Hub

  • config - the parsed config file contents, with ENV var overrides applied
  • isDebug - boolean flag indicating if volante is in debug mode
  • isTesting - boolean flag indicating result of process.env.NODE_ENV === 'test'
  • isProduction - boolean flag indicating result of process.env.NODE_ENV === 'production'

Methods provided by volante.Hub

  • on() - EventEmitter-provided on
  • once() - EventEmitter-provided once
  • emit() - EventEmitter-provided emit
  • attachAll() - find all valid Volante modules
  • attach(name) - attach Volante module by name
  • attachLocal(path) - attach a local JS module
  • attachFromObject(obj) - load a JS object as a Spoke
  • loadConfig(filename) - load a config file from project root
  • get(name) - get a Spoke instance by its given name (name: '<>')
  • getAttached() - return spoke topology, including spoke statuses
  • shutdown() - shutdown Volante

Events emitted by volante.Hub

All Volante built-in events are namespaced with volante. They are listed below along with the data item emitted with the event.

  • volante.configLoaded - config file was fully loaded and all modules included in config have been attached
    String // config filename
  • volante.attachedAll - all Spokes attached using .attachAll()
    Number // number of Spoke modules found
  • volante.attached -
    String // name of Spoke module
  • volante.log - log event
    {
      ts: Date,
      lvl: 'normal', // or 'debug', 'warning', 'error'
      src: String, // Spoke class name
      msg: Any
    }
  • volante.shutdown - emitted when shutdown initiated
  • volante.done - emitted when shutdown complete

Volante Spokes

Volante modules are called Spokes and simply export an object with some predefined members. The object is automatically parsed and instantiated into the Volante framework. The API is heavily influenced by the Vue.js-v2 frontend framework.

Example Spoke Definition

module.exports = {
  name: 'ExampleSpoke',
  props: {
    // effectively the public properties of the module,
    // updated by the config file or real-time by the '<name>.update' event
    someProp: true,
    port: 8080,
  },
  stats: {
    // this section is for storing your spoke module's stats,
    // they will be included in the getStatus output by the Hub
    counter: 0,
  },
  init() {
    // constructor-like initialization
    // called after all props and methods are available on 'this'
    this.privData = [0];
    this.someMethod(1);
  },
  done() {
    // destructor-like de-initialization
  },
  events: {
    // events this Spoke subscribes to, can be from this spoke or volante-wide
    'some.event'(arg) {
      // called when Hub receives 'some.event'
      // can use methods, props, or data here, i.e.
      this.someMethod(arg);
    },
    '*'() {
      // event wildcard, will get all volante events
    }
  },
  data() { // private variables, as a function so it can be evaluated in context
    return {
      // initialize private data members for Spoke instance, not meant to be changed from
      // outside the module but this is not enforced by JS
      privData: [1,2,3],
    };
  },
  updated() {
    // called automatically after props are updated in response to the
    // config file or real-time by the 'ExampleSpoke.update' event
    this.someMethod(this.someProp);
  },
  methods: {
    // methods are added to Spoke instance (watch for name collisions with props/data/stats)
    someMethod(arg) {
      // do stuff
      this.someProp = arg;

      // log stuff
      this.$log('called someMethod');

      // send events
      this.$emit('ExampleSpoke.ready', this.someProp);

      // access config file loaded by hub
      switch (this.$hub.config.auth.mechanism) {};

      // special log level which also sets the status for this module as ready,
      // the Hub will report this module as ready unless the module calls this.$error for anything
      this.$ready('connected and good to go');
    },
    async methodUsingAwait() {
      // you can add async in front of your method to enable await
      let result = await this.$.OtherModule.doSomething();
    },
  }
}

Built-in Spoke Properties

  • $hub - a reference to the central volante.Hub
  • $ or $spokes - object of all spokes in wheel, facilitates calling other spoke methods directly
  • $emit - emit an event across volante wheel
  • $isDebug - aliases the this.$hub.isDebug property to check for debug mode

Built-in Spoke Methods

  • $ready(...) - signal that module is ready, also sets internal status-tracking to ready and emits a <name>.ready event
  • $log(...) - normal-level log messages
  • $debug(...) - debug-level log
  • $warn(...) - warning-level log
  • $error(...) - log an error, returns a new Error object which can be thrown, also sets internal state-tracking to error
  • $shutdown() - request a shutdown

Conventions

In general, events should only be used for what events are good for - broadcasting one-way information such as "I'm connected", passing metrics around, or other information that could be useful to the entire wheel.

Events are also appropriate when an abstract API has the potential to be implemented by various different providers. The event names could be kept generic and handled by modules which could be easily switched out (e.g. for different databases) - for a loose-knit application which is easily extensible. The drawback with this scheme is that callbacks must be used as events don't return.

this.$emit('db.find', {}, (err, results) => {
 // handle error or use results
});

More tight-knit applications should probably use methods provided by another module directly. This is fully compatible with newer practices such as async/await and returning a Promise:

let result1 = await this.$.OtherModule.asyncMethod();
let result2 = this.$.OtherModule.usefulMethod().then().catch();

License

ISC

Package Sidebar

Install

npm i volante

Weekly Downloads

15

Version

6.10.0

License

none

Unpacked Size

33.2 kB

Total Files

12

Last publish

Collaborators

  • msmiley