evo-elements

Evo Cloud Basic Elements

evo-elements

This package includes common and basic building elements for all evo projects.

In this version, it includes:

  • Class: defining Class for object-oriented programming
  • Trace: simple console logging with predefined levels and customizable component names
  • States: a basic framework for building a state machine
  • Config: a simple configuration framework to release you from writing similar code in projects
  • DelayedJob: ensure a postponed job won't be scheduled multiple times
npm install evo-elements

or pull directly from github.com and link to your project:

git clone https://github.com/evo-cloud/elements
npm link elements --prefix=node_modules

In your JavaScript code, use

var elements = require('evo-elements');
Class(baseClass, prototype, options);
  • baseClass: baseClass type, optional, default is Object;
  • prototype: the prototype for new class;
  • options: other options like implements and statics, see details below.

The newly defined class.

A simple and quick sample:

var Class = require('evo-elements').Class;
 
var MyClass = Class({
  constructorfunction (value) {
    // this is the constructor 
    this._value = value;
  },
    
  printfunction () {
    console.log(this._value);
  },
  
  // getter/setter is supported 
  get value () {
    return this._value;
  },
  
  set value (value) {
    if (!isFinite(value)) {
      throw new Error('Bad Value');
    }
    this._value = value;
  }
});
 
var myObject = new MyClass(1);
myObject.print(); // get 1 
myObject.value = myObject.value + 100;
myObject.print(); // get 101 

A simple inheritance sample:

var BaseClass = Class({
  constructorfunction (value) {
    this.value = value;
  },
  
  printfunction () {
    console.log('BaseClass: %d', this.value);
  }
});
 
var SubClass = Class(BaseClass, {
  constructorfunction (val1val2) {
    BaseClass.prototype.constructor.call(this, val1 + val2);
  },
  
  printfunction () {
    console.log('SubClass');
    BaseClass.prototype.print.call(this);
  }
});
 
var myObject = new SubClass(1, 2);
myObject instanceof SubClass;   // true 
myObject instanceof BaseClass;  // true 
myObject.print();
// get 
// SubClass 
// BaseClass: 3 

Multiple inheritance with implements

var ActiveBuffer = Class(Buffer, {
  // override Clearable 
  clearfunction () {
    // TODO I hate to be cleared 
    this.emit('cleared');
  }
}, {
  implements: [EventEmitter, Clearable]
});
 
var buffer = new ActiveBuffer().on('cleared', function () { console.log('CLEARED'); });
buffer.clear();
 
buffer instanceof Buffer; // true 
buffer instanceof EventEmitter; // false 
buffer instanceof Clearable;  // false 

Static members

var Singleton = Class({
  constructorfunction () {
    // ... 
  },
  
  workfunction () {
    // ... 
  }
}, {
  statics: {
    get instance () {
      if (!Singleton._instance) {
        Singleton._instance = new Singleton();
      }
      return Singleton._instance;
    }
  }
});
 
Singleton.instance.work();
var trace = Trace(componentName);
trace.error(...);
trace.warn(...);
trace.info(...);
trace.verbose(...);
trace.debug(...);
// aliases 
trace.err(...); // same as error 
trace.log(...); // same as info 
trace.dbg(...); // same as debug 
trace.verb(...); // same as verbose 
  • componentName: a string which will be prefixed to the logged line

The trace object. All the methods follow the same usage as console.log.

The implementation is backed by debug package. You can use environment variable DEBUG to control which information should be logged. See here for details.

A simple state machine.

var states = new States(initialState);
states.transit(newState);
states.from(currState).transit(newState)
  • initialState: optional, initialize the state machine with the provided state.
  • newState: the next state to switch to. It can be an object or a function. If it is a function, it gets invoked when transit happens and is expected to return the new state object.
  • currState: used with from to assert current state must be currState, otherwise transit will not happen.

A state object can provides two methods: enter and leave, both are optional.

state.enter(previousState)

Expects returning a state object for next state. If it is different from current state, transition keeps runing.

state.leave(nextState)

Invoked when the state machine transits to nextState before invoking nextState.enter.

A simple configuration framework to load settings from command line arguments and configuration files. It also provides a global settings object to be shared by all the modules in one project. When using this, we don't need to write logic for parsing command line and loading and configuration files.

the configuration can always be shared in modules by

var conf = require('evo-elements').Config.conf;

Usually in the main script, use

var conf = require('evo-elements').Config.parse(myArgv).conf;

to parse from specified arguments instead of process.argv.

Then, use conf.opts to access all the setting options.

Only one command line option is reserved: -c CONFIG_FILE or --config CONFIG_FILE for long option form. The CONFIG_FILE must be a YAML file, and all the keys are merged into conf.opts. For other options like --option VALUE or --option=VALUE will become: conf.opts[option] = VALUE. VALUE is automatically parsed into Number, String or Boolean, if you want to specify a JSON, use --option=json:JSON_STRING.

If you know process.nextTick or setTimeout, then you know what a DelayedJob instance does. But a little differently. Each time invoking process.nextTick or setTimeout will schedule a job, the job executes as many times as you schedule. With a single instance of DelayedJob, the job is only scheduled once. The next time you schedule before the job gets run, it does nothing.

The usage is simple:

var job = new DelayedJob(function () {
  // Do what you want ... 
});
 
job.schedule(1000); // it will be scheduled in 1 second 
job.schedule();     // you want to scheduled in next tick, but actually do nothing, because already scheduled 
job.schedule(200);  // still do nothing. 

Why is this pattern useful? It is used to collect some small events, and perform all of them in one shot, like:

var queue = [];
var job = new DelayedJob(function () {
  console.log(queue.join(','));
  // clear queue 
  queue = [];
});
 
queue.push('something');
job.schedule();
 
queue.push('something more');
job.schedule();
...
 
// finally, all the message are processed in one shot 
// printed: something,something more 

MIT/X11 License