react 0.0.1 → 0.2.0

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, tasks, options
+  */
+function parseVargs(vargs) {
+  var inOutParamStr = vargs.shift() || '';
+  // if last arg is object, pop it off as options
+  var options = (vargs.length && typeof(vargs[vargs.length - 1]) === 'object') ? vargs.pop() : { };
+  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;

package/lib/finalcb-first-task.js

@@ -0,0 +1,59 @@
+'use strict';
+
+var sprintf = require('sprintf').sprintf;
+var util = require('util');
+
+var STATUS = require('./status.js');
+var VContext = require('./vcon.js');
+
+var OUTTASK_A_REQ = 'ast.outTask.a should be an array of string param names';
+
+function FinalCbFirstSuccTask(taskDef, cbFunc, tasks, vCon) {
+  var self = this;
+  Object.keys(taskDef).forEach(function (k) { self[k] = taskDef[k]; });
+  this.f = cbFunc;
+  this.tasks = tasks;
+  this.vCon = vCon;
+}
+
+function format_error(errmsg, obj) {
+  return sprintf('%s - %s', errmsg, util.inspect(obj));
+}
+
+FinalCbFirstSuccTask.validate = function (taskDef) {
+  var errors = [];
+  if (! (Array.isArray(taskDef.a) &&
+         taskDef.a.every(function (x) { return (typeof(x) === 'string'); }))) {
+    errors.push(format_error(OUTTASK_A_REQ, taskDef));
+  }
+  return errors;
+}
+
+FinalCbFirstSuccTask.create = function (taskDef, cbFunc, tasks, vCon) {
+  if (!(cbFunc && cbFunc instanceof Function)) throw new Error('callback is not a function'); 
+  return new FinalCbFirstSuccTask(taskDef, cbFunc, tasks, vCon);
+};
+
+/**
+   is ready to exit when any task comes back with non-null defined value
+  */
+FinalCbFirstSuccTask.prototype.isReady = function () {
+  var lastres = this.vCon.getLastResults();
+  if (!lastres) return false; // no results yet
+  return (lastres.some(function (v) { return (v !== undefined && v !== null); }));
+};
+
+FinalCbFirstSuccTask.prototype.exec = function (err) {
+  if (!this.f) return;   //must have already been called
+  if (err) {
+    this.f.call(null, err); //call the final callback with the first error hit
+  } else { // no error, call with args
+    var vCon = this.vCon;
+    var finalArgs = this.a.map(function (k) { return vCon.getVar(k); });
+    finalArgs.unshift(null);   //unshift err=null to front
+    this.f.apply(null, finalArgs);
+  }
+  this.f = null;   // prevent multiple calls
+};
+
+module.exports = FinalCbFirstSuccTask;

package/lib/finalcb-task.js

@@ -0,0 +1,54 @@
+'use strict';
+
+var sprintf = require('sprintf').sprintf;
+var util = require('util');
+
+var STATUS = require('./status.js');
+
+var OUTTASK_A_REQ = 'ast.outTask.a should be an array of string param names';
+
+function FinalCbTask(taskDef, cbFunc, tasks, vCon) {
+  var self = this;
+  Object.keys(taskDef).forEach(function (k) { self[k] = taskDef[k]; });
+  this.f = cbFunc;
+  this.tasks = tasks;
+  this.vCon = vCon;
+}
+
+function format_error(errmsg, obj) {
+  return sprintf('%s - %s', errmsg, util.inspect(obj));
+}
+
+
+FinalCbTask.validate = function (taskDef) {
+  var errors = [];
+  if (! (Array.isArray(taskDef.a) &&
+         taskDef.a.every(function (x) { return (typeof(x) === 'string'); }))) {
+    errors.push(format_error(OUTTASK_A_REQ, taskDef));
+  }
+  return errors;
+};
+
+FinalCbTask.create = function (taskDef, cbFunc, tasks, vCon) {
+  if (!(cbFunc && cbFunc instanceof Function)) throw new Error('callback is not a function'); 
+  return new FinalCbTask(taskDef, cbFunc, tasks, vCon);
+};
+
+FinalCbTask.prototype.isReady = function () {
+  return (this.tasks.every(function (t) { return (t.status === STATUS.COMPLETE); }));
+};
+
+FinalCbTask.prototype.exec = function (err) {
+  if (!this.f) return;   //must have already been called
+  if (err) {
+    this.f.call(null, err); //call the final callback with the first error hit
+  } else { // no error, call with args
+    var vCon = this.vCon;
+    var finalArgs = this.a.map(function (k) { return vCon.getVar(k); });
+    finalArgs.unshift(null);   //unshift err=null to front
+    this.f.apply(null, finalArgs);
+  }
+  this.f = null;   // prevent multiple calls
+};
+
+module.exports = FinalCbTask;

package/lib/fstr.js

@@ -0,0 +1,110 @@
+'use strict';
+
+var sprintf = require('sprintf').sprintf;
+var core = require('./core.js');
+var parse = require('./parse.js');
+var tutil = require('./task.js');
+
+var INPARAMS_NO_MATCH = 'input params in wrong format, wanted "foo, bar" -  found: %s';
+var OUTPARAMS_NO_MATCH = 'output params in wrong format, wanted "foo, bar" - found: %s';
+var INOUT_PARAMS_NO_MATCH = 'task params in wrong format, wanted "foo, bar -> err, baz" - found: %s';
+var EXTRA_TASKARG = 'extra unmatched task arg: %s';
+
+var inOutDefParse = {
+  regex: /^([^-]*)(->)?\s*(er{0,2}\s*,|returns?\s+)?(.*)$/i,
+  fn: function (m) {
+    var reMatchReturns = /returns?/i;
+    return {
+      type: (m[3] && m[3].match(reMatchReturns)) ? 'ret' : 'cb',
+      inDef: parse.splitTrimFilterArgs(m[1]),
+      outDef: parse.splitTrimFilterArgs(m[4])
+    };
+  }
+};
+
+function filterOutTrailingCbParam(args) { // if has trailing cb | callback param, filter it out
+  var cbNamesRe = /^cb|callback$/i;  //cb, Cb, CB, callback, Callback
+  if (args.length && args[args.length - 1].match(cbNamesRe)) args.pop();
+  return args;
+}
+
+function parseInParams(str) {
+  var objDef = parse.parseStr(str, [inOutDefParse], INPARAMS_NO_MATCH);
+  objDef.inDef = filterOutTrailingCbParam(objDef.inDef);
+  return objDef;
+}
+
+function parseInOutParams(str) {
+  var objDef = parse.parseStr(str, [inOutDefParse], INOUT_PARAMS_NO_MATCH);
+  objDef.inDef = filterOutTrailingCbParam(objDef.inDef);
+  return objDef;
+}
+
+function parseOutParams(str) {
+  if (str.indexOf('->') === -1) str = '-> ' + str; // prefix so does out err process
+  return parse.parseStr(str, [inOutDefParse], OUTPARAMS_NO_MATCH);
+} 
+
+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;
+}
+
+
+function fstrDefine(inParamStr, taskDefArr, outParamStr, options) {
+  if (!inParamStr) inParamStr = '';
+  if (!taskDefArr) taskDefArr = [];
+  if (!outParamStr) outParamStr = '';
+
+  var reactFn = core();
+  var ast = {
+    inParams: parseInParams(inParamStr).inDef,
+    tasks: parseTasks(taskDefArr),
+    outTask: { a: parseOutParams(outParamStr).outDef }
+  };
+  if (options) Object.keys(options).forEach(function (k) { ast[k] = options[k]; });
+  var errors = reactFn.setAndValidateAST(ast);
+  if (errors.length) {
+    var errorStr = errors.join('\n');
+    throw new Error(errorStr);
+  }
+  return reactFn;
+}
+
+function selectFirst(inParamStr, taskDefArr, outParamStr, options) {
+  if (!inParamStr) inParamStr = '';
+  if (!taskDefArr) taskDefArr = [];
+  if (!outParamStr) outParamStr = '';
+  var tasks = tutil.serializeTasks(parseTasks(taskDefArr));
+
+  var reactFn = core();
+  var ast = {
+    inParams: parseInParams(inParamStr).inDef,
+    tasks: tasks,
+    outTask: { type: 'finalcbFirst', a: parseOutParams(outParamStr).outDef },
+  };
+  if (options) Object.keys(options).forEach(function (k) { ast[k] = options[k]; });  
+  var errors = reactFn.setAndValidateAST(ast);
+  if (errors.length) {
+    var errorStr = errors.join('\n');
+    throw new Error(errorStr);
+  }
+  return reactFn;
+}
+
+module.exports = fstrDefine;
+module.exports.selectFirst = selectFirst;