react 0.0.2 → 0.2.1

package/lib/chain.js

@@ -0,0 +1,148 @@
+'use strict';
+
+var sprintf = require('sprintf').sprintf;
+var core = require('./core.js');
+var tutil = require('./task.js');
+
+// err for task type cb is implied and thus optional, but allow for clarity. 
+var ERROR_NAMES_RE = /^err$/i;  // first out param matching this is skipped as being the err object
+
+// callback is implied for task type cb is implied and thus optional, but allow for clarity. 
+var CALLBACK_NAMES_RE = /^cb$|^callback$/i;  // last in param matching this is skipped as being the cb
+
+var FlowBuilder;
+
+/**
+   jQuery-like chain interface for defining flow
+
+   @example
+    // normal flow
+    var react = require('react');
+    var fn = react.chainDefine()
+      .in('filename', 'uid', 'outDirname', 'cb')
+      .out('err', 'html', 'user', 'bytesWritten')  
+      .async(loadUser)          .in('uid')               .out('err', 'user')
+      .async(loadFile)          .in('filename')          .out('err', 'filedata')
+      .sync(markdown)           .in('filedata')          .out('html')
+      .async(prepareDirectory)  .in('outDirname')        .out('err', 'dircreated') 
+      .async(writeOutput)       .in('html', 'user')      .out('err', 'bytesWritten')   .after('prepareDirectory')
+      .async(loadEmailTemplate) .in()                    .out('err', 'emailmd')
+      .sync(markdown)           .in('emailmd')           .out('emailHtml')
+      .sync(customizeEmail)     .in('user', 'emailHtml') .out('custEmailHtml')
+      .async(deliverEmail)      .in('custEmailHtml')     .out('err', 'deliveredEmail') .after('writeOutput')
+      .end();
+
+   @example
+    // selectFirst flow
+    var fn = chainDefine()
+      .selectFirst()
+      .in('a', 'b', 'cb')
+      .out('err', 'c')
+      .async(falpha).in('a', 'b', 'cb').out('err', 'c')
+      .sync(fbeta).in('a', 'b').out('c')
+      .end();    
+*/
+function chainDefine() {
+  return FlowBuilder.create();
+}
+
+function FlowBuilder() {
+  this.main = {
+    name: null,
+    options: {}
+  };
+  this.tasks = [];
+  this.focus = this.main;
+}
+
+FlowBuilder.create = function () { return new FlowBuilder(); };
+
+FlowBuilder.prototype.selectFirst = function () {
+  this.main.outTaskType = 'finalcbFirst';
+  return this;
+};
+
+FlowBuilder.prototype.name = function (name) {
+  this.focus.name = name;
+  return this;
+};
+
+FlowBuilder.prototype.in = function (param1, param2, paramN) { 
+  var args = Array.prototype.slice.call(arguments);
+  if (args.length && this.focus.type !== 'ret') {  // has args and cb or main
+    if (args[args.length - 1].match(CALLBACK_NAMES_RE)) args.pop(); // pop off the cb name if specified
+  }
+  if (this.focus === this.main) this.focus.in = args;
+  else this.focus.a = args;   // for tasks
+  return this;
+};
+
+FlowBuilder.prototype.out = function (param1, param2, paramN) {
+  var args = Array.prototype.slice.call(arguments);
+  if (args.length && this.focus.type !== 'ret') {  // has args and cb or main
+    if (args[0].match(ERROR_NAMES_RE)) args.shift(); // shift off err if specified
+  }
+  this.focus.out = args;
+  return this;
+};
+
+FlowBuilder.prototype.options = function (options) {
+  var self = this;
+  if (this.focus === this.main) {
+    Object.keys(options).forEach(function (k) { self.focus.options[k] = options[k]; });
+  } else { // task so set options right on task
+    Object.keys(options).forEach(function (k) { self.focus[k] = options[k]; });
+  }
+  return this;
+};
+
+FlowBuilder.prototype.async = function (funcOrStrMethod) {
+  var task = { f: funcOrStrMethod, type: 'cb' };
+  this.tasks.push(task);
+  this.focus = task;
+  return this;
+};
+
+FlowBuilder.prototype.sync = function (funcOrStrMethod) {
+  var task = { f: funcOrStrMethod, type: 'ret' };
+  this.tasks.push(task);
+  this.focus = task;
+  return this;
+};
+
+FlowBuilder.prototype.after = function (name1, name2, nameN) {
+  this.focus.after = Array.prototype.slice.call(arguments);
+  return this;
+};
+
+/**
+   Complete the building of a flow and perform validation
+   which throws error if flow is not valid.
+  */
+FlowBuilder.prototype.end = function end() {
+  var reactFn = core();
+
+  if (this.main.outTaskType === 'finalcbFirst') {
+    this.tasks = tutil.serializeTasks(this.tasks);
+  }
+
+  var ast = {
+    inParams: this.main.in || [],
+    tasks: this.tasks,
+    outTask: {
+      a: this.main.out || [],
+      type: this.main.outTaskType || 'finalcb'
+    }
+  };
+  if (this.main.name) ast.name = this.main.name;
+  var self = this;
+  Object.keys(this.main.options).forEach(function (k) { ast[k] = self.main.options[k]; });
+  var errors = reactFn.setAndValidateAST(ast);
+  if (errors.length) {
+    var errorStr = errors.join('\n');
+    throw new Error(errorStr);
+  }
+  return reactFn;
+};
+
+module.exports = chainDefine;

package/lib/core.js

@@ -0,0 +1,96 @@
+'use strict';
+
+var EventEmitter = require('events').EventEmitter;
+
+var error = require('./error.js');
+var validate = require('./validate.js');
+var tskutil = require('./task.js');
+var STATUS = require('./status.js');
+var VContext = require('./vcon.js');
+var FinalCbTask = require('./finalcb-task.js');
+var EventManager = require('./event-manager.js');
+var inputParser = require('./input-parser.js');
+var idGenerator = require('./id.js');
+
+var reactOptions = {
+  stackTraceLimitMin: 30  
+};
+
+var reactEmitter = EventManager.create(); // the top emitter
+
+/**
+   Creates react function which the AST can be manipulated and then
+   is ready to be executed. Can be used directly or a DSL can wrap this
+   to provide the AST.
+
+   @example
+   var react = require('react');
+   var fn = react();
+   var valid2 = fn.setAndValidateAST({
+     name: 'optionalName',
+     inParams: ['a', 'b'],
+     tasks: [
+      { type: 'cb', f: multiply, a: ['a', 'b'], out: ['c'] }
+     ],
+    outTask: { a: ['c'] }
+   });
+   console.log(fn.ast); // view
+   fn(123, 456, cb);
+ */
+function reactFactory() {
+  if (arguments.length) throw new Error('react() takes no args, check API');
+  
+  error.ensureStackTraceLimitSet(reactOptions.stackTraceLimitMin);
+  var flowEmitter = EventManager.create();
+  flowEmitter.parent = reactEmitter;
+
+  var ast = {
+    name: undefined,
+    inParams: [],
+    tasks: [],
+    outTask: {},
+    locals: {}
+  };
+
+  function setAndValidateAST(newAST) { //set AST then validate, ret error[]
+    Object.keys(newAST).forEach(function (k) { ast[k] = newAST[k]; }); // copy all properties
+    var errors = validate(ast);
+    if (!errors.length) tskutil.nameTasks(ast.tasks); //run this so names can be checked in ast
+    return errors;
+  }
+
+  function exec(arg1, arg2, argN, cb) { // called to execute the flow
+    var parsedInput = inputParser(Array.prototype.slice.call(arguments), ast);
+    var args = parsedInput.args;
+    var cbFinal = parsedInput.cb;
+    var extraArgs = parsedInput.extraArgs; // we'll have these if we need them
+    var vCon = VContext.create(args, ast.inParams, ast.locals); // create var ctx with in args & locals
+    var tasks = ast.tasks.map(tskutil.create);
+    var tasksByName = tskutil.nameTasks(tasks); // map names to working tasks
+    var outTask = tskutil.createOutTask(ast.outTask, cbFinal, tasks, vCon);
+    var handleError = tskutil.createErrorHandler(vCon, outTask);
+
+    function contExec() {
+      if (!outTask.f) { return; } //stop execution, we already hit an error, f was cleared
+      if (outTask.isReady()) return outTask.exec(); // all tasks done, exec cb, return
+      tskutil.findReadyAndExec(vCon, tasks, tasksByName, handleError, contExec);  //exec tasks that ready to run
+    }
+    
+    tasks.forEach(function (t) {
+      t.id = idGenerator.createUniqueId();
+      t.flowEmitter = flowEmitter;
+      if (t.type === 'cb') t.cbFun = tskutil.createCallback(t, handleError, vCon, contExec, flowEmitter);
+    }); // create callbacks
+    contExec();   // start things off
+  }
+
+  var reactFn = exec;        // make the exec() the function returned
+  reactFn.ast  = ast;        // put AST hanging off the fn so it can be inspected
+  reactFn.setAndValidateAST = setAndValidateAST;   // call to set AST and then validate
+  reactFn.events = flowEmitter; // used to listen to execution events for this flow
+  return reactFn;
+}
+
+module.exports = reactFactory;           // module returns reactFactory to create a react fn
+module.exports.options = reactOptions;   // global react options
+module.exports.events = reactEmitter;    // global react emitter

package/lib/dsl.js

@@ -0,0 +1,122 @@
+'use strict';
+/*jshint regexp: false */
+
+var sprintf = require('sprintf').sprintf;
+var core = require('./core.js');
+var parse = require('./parse.js');
+var tutil = require('./task.js');
+
+var INOUT_PARAMS_NO_MATCH = 'params in wrong format, wanted "foo, bar cb -> err, baz" - found: %s';
+var EXTRA_TASKARG = 'extra unmatched task arg: %s';
+
+var CB_NAMES_RE = /^cb|callback$/i;  //cb, Cb, CB, callback, Callback
+var ERR_NAMES_RE = /^err$/i; // err, ERR, Err, ...
+
+function filterOutTrailingCbParam(args) { // if has trailing cb | callback param, filter it out
+  if (args.length && args[args.length - 1].match(CB_NAMES_RE)) args.pop();
+  return args;
+}
+
+function filterOutLeadingErrParam(args) { // if leading err param, filter it out
+  if (args.length && args[0].match(ERR_NAMES_RE)) args.shift();
+  return args;
+}
+
+var inOutDefParse = {
+  regex: /^([^\-]*)(->\s*(.*))?$/i,
+  fn: function (m) {
+    var inParams = parse.splitTrimFilterArgs(m[1]);
+    var lastParam = inParams[inParams.length - 1];
+    var type = (lastParam && CB_NAMES_RE.test(lastParam)) ? 'cb' : 'ret';
+    var outParams = parse.splitTrimFilterArgs(m[3]);
+    return {
+      type: type,
+      inDef: filterOutTrailingCbParam(inParams),
+      outDef: filterOutLeadingErrParam(outParams)
+    };
+  }
+};
+
+function parseInOutParams(str) {
+  var objDef = parse.parseStr(str, [inOutDefParse], INOUT_PARAMS_NO_MATCH);
+  objDef.inDef = filterOutTrailingCbParam(objDef.inDef);
+  return objDef;
+}
+
+function parseTasks(arr) {
+  var tasks = [];
+  var fn, obj, result;
+  while (arr.length >= 2) {
+    obj = {};
+    fn = arr.shift();
+    result = parseInOutParams(arr.shift());
+    if (typeof(arr[0]) === 'object') obj = arr.shift(); // has options, use as obj
+    obj.f = fn;
+    obj.a = result.inDef;
+    var type = result.type;
+    obj.out = result.outDef;
+    obj.type = type;
+    tasks.push(obj);
+  }
+  if (arr.length) throw new Error(sprintf(EXTRA_TASKARG, arr[0]));
+  return tasks;
+}
+
+/**
+   Parse the variable arguments into in/out params, options, tasks
+  */
+function parseVargs(vargs) {
+  var inOutParamStr = vargs.shift() || '';
+  // if next arg is object, shift it off as options
+  var options = (vargs.length && typeof(vargs[0]) === 'object') ? vargs.shift() : { };
+  var taskDefArr = vargs; // rest are for the tasks
+  var defObj = {  
+    inOutParamStr: inOutParamStr,
+    taskDefArr: taskDefArr,
+    options: options
+  };
+  return defObj;
+}
+
+
+function dslDefine(name, arg1, arg2, argN) {
+  var reactFn = core();
+  var defObj = parseVargs(Array.prototype.slice.call(arguments, 1)); // name, already used 
+  var inOutDef = parseInOutParams(defObj.inOutParamStr);
+  var ast = {
+    name: name,
+    inParams: inOutDef.inDef,
+    tasks: parseTasks(defObj.taskDefArr),
+    outTask: { a: inOutDef.outDef }
+  };
+  if (defObj.options) Object.keys(defObj.options).forEach(function (k) { ast[k] = defObj.options[k]; });
+  var errors = reactFn.setAndValidateAST(ast);
+  if (errors.length) {
+    var errorStr = errors.join('\n');
+    throw new Error(errorStr);
+  }
+  return reactFn;
+}
+
+function selectFirst(name, arg1, arg2, argN) {
+  var reactFn = core();
+  var defObj = parseVargs(Array.prototype.slice.call(arguments, 1)); // name, already used 
+  var inOutDef = parseInOutParams(defObj.inOutParamStr);  
+  var tasks = tutil.serializeTasks(parseTasks(defObj.taskDefArr));
+  var ast = {
+    name: name,
+    inParams: inOutDef.inDef,
+    tasks: tasks,
+    outTask: { type: 'finalcbFirst', a: inOutDef.outDef },
+  };
+  if (defObj.options) Object.keys(defObj.options).forEach(function (k) { ast[k] = defObj.options[k]; });  
+  var errors = reactFn.setAndValidateAST(ast);
+  if (errors.length) {
+    var errorStr = errors.join('\n');
+    throw new Error(errorStr);
+  }
+  return reactFn;
+}
+
+module.exports = dslDefine;
+module.exports.selectFirst = selectFirst;

package/lib/error.js

@@ -0,0 +1,37 @@
+'use strict';
+
+var util = require('util');
+
+function ensureStackTraceLimitSet(stackTraceLimit) {
+  if (!Error.stackTraceLimit || Error.stackTraceLimit < stackTraceLimit) {
+    Error.stackTraceLimit = stackTraceLimit;
+  }
+}
+
+function fName(fn) {
+  return (typeof(fn) === 'string') ? fn : fn.name;
+}
+
+function formatErrorMeta(err) {
+  if (!err.meta) return;
+  var vcon = err.meta.vcon;
+  var task = err.meta.task;
+  return '\n\n' +
+      'Error occurs in Task function: ' + fName(task.f) + '(' + task.a.join(',') + ')\n\n' + 
+      'Variable Context: \n' +
+      util.inspect(vcon) + '\n\n' +
+      'Task Source:\n\n' +
+      task.f.toString() + '\n\n'; //TODO need to pretty print function, gets collapsed
+}
+
+function augmentError(err, meta) {
+  if (typeof(err) === 'string') { err = new Error(err); } //props will be lost on non-objects
+  var origMsg = err.toString();
+  err.meta = meta;
+  err.toString = function () { return origMsg + formatErrorMeta(err); };
+  return err;
+}
+
+
+exports.ensureStackTraceLimitSet = ensureStackTraceLimitSet;
+exports.augmentError = augmentError;

package/lib/event-manager.js

@@ -0,0 +1,57 @@
+'use strict';
+
+var EventEmitter2 = require('eventemitter2').EventEmitter2;
+
+var EVENT_EMITTER2_CONFIG = {
+  wildcard: true
+};
+
+var TYPES = {
+  TASK_BEGIN: 'task.begin',
+  TASK_COMPLETE: 'task.complete'
+};
+
+/**
+   Event manager which emits events up to its parent if exists.
+   Allows a hierarchy of emitters, which communicate up the
+   chain.
+  */
+function EventManager() {
+}
+
+EventManager.create = function () { return new EventManager(); };
+
+EventManager.prototype.isEnabled = function () { // if has listener or an ancestor has listener
+  return (this.emitter || (this.parent && this.parent.isEnabled()));
+};
+
+/**
+   Add listener. Wildcard events are allowed like 'foo.*'
+   Use '*' to listen to any event
+  */
+EventManager.prototype.on = function (event, listener) {
+  if (!this.emitter) this.emitter = new EventEmitter2(EVENT_EMITTER2_CONFIG);
+  if (event === '*') this.emitter.onAny(listener);
+  else this.emitter.on(event, listener);
+};
+
+EventManager.prototype.emit = function (event, arg1, arg2, argN) {
+  if (this.emitter) this.emitter.emit.apply(this.emitter, arguments);
+  if (this.parent && this.parent.isEnabled()) this.parent.emit.apply(this.parent, arguments);
+};
+
+/**
+   Emit an object augmented with standard fields.
+   Copies object and adds standard fields:
+    event: event type
+    time: current time
+  */
+EventManager.prototype.emitObject = function (event, object) {
+  var evObj = Object.create(object); // create inherited copy version so origin is untouched
+  evObj.event = event;     // augment with the event type
+  evObj.time = Date.now(); // augument with the time of the event
+  this.emit(event, evObj);
+};
+
+module.exports = EventManager;
+module.exports.TYPES = TYPES;