vargate v0.9.4

VarGate

VarGate is an async library designed around data instead of files.

Including VarGate

Browser

<script src="path/to/vargate.min.js"></script>

VarGate is now available via window.VarGate.

Node

Run npm install vargate --save-dev.

If using ES6:

import VarGate from "vargate";

CommonJS:

var VarGate = require('vargate');

AMD:

define(['vargate'], function(VarGate) {

});

Overview

Think of VarGate as RequireJS for variables instead of files. It turns this:

// jQuery used for brevity. This is not a jQuery library
var someVar, anotherVar, aThirdVar;
$.get('/some-endpoint')
    .done(function(resp) {
        someVar = resp.data;
        return $.get('/another-endpoint');
    }).done(function(resp) {
        anotherVar = resp.data;
        return $.get('/a-third-endpoint');
    }).done(function(resp) {
        aThirdVar = resp.data;
        console.log("I have some " + someVar + ", as well as some " + anotherVar + " and " + aThirdVar + ".");
    });

into this:

VarGate.when([
    'someVar',
    'anotherVar',
    'aThirdVar'
], function(someVar, anotherVar, aThirdVar) {
    console.log("I have some " + someVar + ", as well as some " + anotherVar + " and " + aThirdVar + ".");
});
$.get('/some-endpoint', function(resp) {
    VarGate.set('someVar', resp.data);
});
$.get('/another-endpoint', function(resp) {
    VarGate.set('anotherVar', resp.data);
});
$.get('/a-third-endpoint', function(resp) {
    VarGate.set('aThirdVar', resp.data);
});

Usage

When developing, it is recommended to set window.DEBUG_MODE and window.DEV_MODE.

window.DEV_MODE = 'strict'; // Errors will stop execution. Recommended for local development.
window.DEV_MODE = 'warn';   // Errors will log, but execution will continue. Recommended for staging environments.
window.DEBUG_MODE = 'verbose'; // Will log the trace of every action
window.DEBUG_MODE = 'static'; // Same as verbose, but prints a static copy of the values passed through
window.DEBUG_MODE = 'minimal'; // Will only log `VarGate.set` actions

Without setting window.DEV_MODE, errors will be ignored, as it is assumed you are in a production environment. Likewise, not setting window.DEBUG_MODE will silence the log statements from VarGate.

When waiting on a single variable to be defined

VarGate.when('oneVar', func);

When waiting on multiple variables to be defined

VarGate.when(['oneVar', 'twoVar'], func);

When waiting on multiple variables to meet specific conditions, follow the convention [key, operator, value]

VarGate.when([['oneVar', '===',  7], ['twoVar', '>', 4]], func);

When waiting on one variable to meet a specific condition (in this case, equaling another variable)

VarGate.when([['oneVar', '===', '@twoVar']],  func);

When waiting on the nested property of a variable to be defined:

VarGate.when([[someObject, 'someProperty']],  func); //note: this will return `someObject` in the callback

Functions will only run once. To run a function every time data is changed, use the following:

VarGate.on('someVar', func); // Will run every time `someVar` is set
VarGate.on([['someVar', '===', 3]], func); // Will run every time `someVar` is set to 3
VarGate.on(['someVar', 'anotherVar'], on); // Will run every time `someVar` and `anotherVar` are set

To un-set a variable, just do VarGate.unset('someVar'), which will set the variable to undefined.

To clear all data in a given module, use VarGate.clear(). Note that this will not clear sub-modules.

To clear all data in a given module, as well as all sub-modules, use VarGate.clearAll().

You can namespace sub-modules to avoid name conflicts

var subGate = VarGate.register('subgate');
subGate.set('someVar', someValue);
var otherGate = subGate.register('othergate');
otherGate.set('someVar', anotherValue); // will error out if window.DEV_MODE == 'strict'
console.log(subGate.get('someVar') == otherGate.get('someVar')); // prints `false`

The parent can get and set values for its children

VarGate.set('subgate.value', anotherValue);
VarGate.get('othergate.someVar');

Sub-modules can only get values from the parent

VarGate.set('value', 1);
var subGate = VarGate.register('subgate');
subGate.get('value'); // returns 1
subGate.set('value', 3); // will error out if window.DEV_MODE == 'strict'
subGate.get('value'); // returns 3
VarGate.get('value'); // returns 1

To override a value set in a parent module, use the override function:

var subGate = VarGate.register('subgate');
VarGate.set('val', 3);
subGate.override('val', 'ten'); // will not error out!
subGate.get('val'); // returns 'ten'
VarGate.get('val'); // returns 3