react 0.0.2 → 0.2.1

package/lib/ret-task.js

@@ -0,0 +1,67 @@
+'use strict';
+
+var util = require('util');
+var sprintf = require('sprintf').sprintf;
+
+var BaseTask = require('./base-task.js');
+
+function format_error(errmsg, obj) {
+  return sprintf('%s - %s', errmsg, util.inspect(obj));
+}
+
+var REQ = 'retTask requires f, a, out';
+var FN_REQ = 'retTask requires f to be a function or string';
+var A_REQ = 'retTask requires a to be an array of string param names';
+var RET_REQ = 'retTask requires out to be an array with single string param name or []';
+
+function RetTask(taskDef) {
+  var self = this;
+  Object.keys(taskDef).forEach(function (k) { self[k] = taskDef[k]; });
+}
+
+RetTask.prototype = new BaseTask();
+RetTask.prototype.constructor = RetTask;
+
+RetTask.validate = function (taskDef) {
+  var errors = [];
+  if (!taskDef.f || !taskDef.a || !taskDef.out) {
+    errors.push(format_error(REQ, taskDef));
+  } else {
+    var ftype = typeof(taskDef.f);
+    if (! ((taskDef.f instanceof Function) || (ftype === 'string'))) {
+      errors.push(format_error(FN_REQ, taskDef));
+    }
+    if (! (Array.isArray(taskDef.a) &&
+           taskDef.a.every(function (x) { return (typeof(x) === 'string'); }))) {
+      errors.push(format_error(A_REQ, taskDef));
+    }
+
+    if (! (Array.isArray(taskDef.out) &&
+           (taskDef.out.length === 0 ||
+             (taskDef.out.length === 1 && typeof(taskDef.out[0] === 'string'))))) {
+      errors.push(format_error(RET_REQ, taskDef));
+    }
+  }
+  return errors;
+};
+
+RetTask.prototype.exec = function exec(vCon, handleError, contExec) {
+  try {
+    var args = this.a.map(function (k) { return vCon.getVar(k); }); //get args from vCon
+    this.start(args); //note the start time, args    
+    var func = this.f;
+    var bindObj = null; //global space
+    if (this.isMethodCall()) { //if method call then reset func and bindObj
+      func = vCon.getVar(this.f);
+      bindObj = this.getMethodObj(vCon);
+    } else if (typeof(func) === 'string') {
+      func = vCon.getVar(func); // we want the actual fn from this string
+    }
+    var results = [func.apply(bindObj, args)];
+    vCon.saveResults(this.out, results); // save retval, takes arrays
+    this.complete(results);
+    contExec();       // continue since no callback to run this
+  } catch (err) { handleError(this, err); }    // catch and handle the task error, calling final cb
+};
+
+module.exports = RetTask;

package/lib/status.js

@@ -0,0 +1,5 @@
+'use strict';
+
+var STATUS = { READY: 'ready',  RUNNING: 'running', ERRORED: 'errored', COMPLETE: 'complete' };
+
+module.exports = STATUS;

package/lib/task.js

@@ -0,0 +1,234 @@
+'use strict';
+
+var util = require('util');
+var sprintf = require('sprintf').sprintf;
+var array = require('ensure-array');
+var CbTask = require('./cb-task.js');
+var RetTask = require('./ret-task.js');
+var FinalCbTask = require('./finalcb-task.js');
+var FinalCbFirstSuccTask = require('./finalcb-first-task.js');
+var STATUS = require('./status.js');
+var error = require('./error.js');
+var VContext = require('./vcon.js');
+
+var TASK_TYPES = {
+  cb: CbTask,
+  ret: RetTask
+};
+function taskTypeKeys() { return Object.keys(TASK_TYPES); }
+
+var OUT_TASK_TYPES = {
+  finalcb: FinalCbTask,   //first task is the default if no type specified in taskDef
+  finalcbFirst: FinalCbFirstSuccTask
+};
+function outTaskTypeKeys() { return Object.keys(OUT_TASK_TYPES); }
+
+var LOCAL_FN_MISSING = 'function: %s not found in locals or input params - task[%s]';
+var TASKDEF_IS_OBJECT = 'task must be an object';
+var NO_TASKS_RUNNING_WONT_COMPLETE = 'no tasks running, flow will not complete';
+var TASK_TYPE_SHOULD_MATCH = 'task.type should match one of ' +
+  Object.keys(TASK_TYPES).join(', ');
+
+var validateTaskType, validateTask, create;
+
+
+function format_error(errmsg, obj) {
+  return sprintf('%s - %s', errmsg, util.inspect(obj));
+}
+
+/**
+   guess the missing types from params.
+   Augments in place but also returns taskDef.
+   If not specified then is 'cb'
+  */
+function setMissingType(taskDef) {
+  if (taskDef.type) return taskDef; //already set, return
+  taskDef.type = 'cb'; 
+  return taskDef;
+}
+
+function setMissingOutTaskType(taskDef) {
+  if (!taskDef.type) taskDef.type = Object.keys(OUT_TASK_TYPES)[0]; //use first outTask type as default
+} 
+
+function ensureAfterArrStrings(taskDef) { // convert any fn to str, and make sure is array
+  if (!taskDef.after) return;
+  var afterArr = array(taskDef.after);  // ensure is array, null becomes []
+  afterArr = afterArr.map(function (a) { return (typeof(a) === 'function') ? a.name : a; });
+  taskDef.after = afterArr;
+}
+
+/**
+   @returns array of errors for taskDef, could be empty
+  */
+function validate(taskDef) {
+  if (!taskDef || typeof(taskDef) !== 'object') {    
+    return [format_error(TASKDEF_IS_OBJECT, taskDef)];
+  }
+  setMissingType(taskDef);
+  ensureAfterArrStrings(taskDef);
+  var errors = [];
+  errors = errors.concat(validateTaskType(taskDef));
+  errors = errors.concat(validateTask(taskDef));  
+  return errors;
+}
+
+function validateTaskType(taskDef) {
+  var errors = [];
+  if (!Object.keys(TASK_TYPES).some(
+    function (type) { return (taskDef.type === type); })) {
+    errors.push(format_error(TASK_TYPE_SHOULD_MATCH, taskDef));
+  }
+  return errors;
+}
+
+function validateTask(taskDef) {
+  var errors = [];
+  var taskCons = TASK_TYPES[taskDef.type];
+  if (taskCons) {
+    errors = errors.concat(taskCons.validate(taskDef));
+  }
+  return errors;
+}
+
+function validateOutTask(taskDef) {
+  var errors = [];
+  setMissingOutTaskType(taskDef);
+  var taskCons = OUT_TASK_TYPES[taskDef.type];
+  errors = errors.concat(taskCons.validate(taskDef));
+  return errors;  
+}
+
+
+function validateLocalFunctions(inParams, taskDefs, locals) {
+  var errors = [];
+  function foo() { } //used to mock args as fns for validation check 
+  var mock_args = inParams.map(function (p) { return foo; }); //mock args with fns
+  var vCon = VContext.create(mock_args, inParams, locals);
+  var tasks = taskDefs.map(create);
+  tasks.forEach(function (t, idx) {
+    if (!t.functionExists(vCon)) {   // error if function doesnt exist AND
+      if (!t.isMethodCall()) errors.push(sprintf(LOCAL_FN_MISSING, t.f, idx)); // not method OR
+      else {
+        var obj = t.getMethodObj(vCon);
+        if (obj && obj !== foo) {  // (has parent but not our mock)
+          errors.push(sprintf(LOCAL_FN_MISSING, t.f, idx));
+        }
+      }
+    }
+  });
+  return errors;
+}
+
+function fName(fn) {
+  return (typeof(fn) === 'string') ? fn : fn.name;
+}
+
+/**
+   Name tasks that are not already named. Prenamed task uniquness validation
+   will be done in validate.
+
+   This modifies the tasks with the new names.
+
+   @returns map of names to tasks
+  */
+function nameTasks(tasks) { //name tasks that are not already named, validation done elsewhere, ret map
+  var namesMap = tasks.reduce(function (map, t) {
+    if (t.name) { map[t.name] = t; }
+    return map;
+  }, {});
+  tasks.forEach(function (t, idx) {
+    if (!t.name) { //not already named
+      var name = fName(t.f);
+      if (!name || namesMap[name]) {
+        name = sprintf('%s_%s', name, idx); //if empty or already used, postfix with _idx
+      }
+      t.name = name;
+      namesMap[name] = t;
+    }
+  });
+  return namesMap;
+}
+
+function create(taskDef) {
+  var TaskConstructor = TASK_TYPES[taskDef.type];
+  return new TaskConstructor(taskDef);
+}
+
+function createOutTask(taskDef, cbFinal, tasks, vCon) {
+  setMissingOutTaskType(taskDef);
+  var TaskConstructor = OUT_TASK_TYPES[taskDef.type];
+  return new TaskConstructor(taskDef, cbFinal, tasks, vCon);
+}
+  
+function createCallback(task, handleTaskError, vCon, contExec) {
+  return function (err, arg0, arg1, argn) {
+    var args = Array.prototype.slice.call(arguments, 1);
+    if (err) { handleTaskError(task, err); return; } //handle error and return, we are done
+
+    //no error, save callback args to vCon context, then continue execution
+    vCon.saveResults(task.out, args);
+    task.complete(args);
+    contExec();
+  };
+}
+
+function createErrorHandler(vCon, outTask) {
+  return function handleError(task, err) {
+    task.status = STATUS.ERRORED;
+    var errWithMeta = error.augmentError(err, {task: task, vcon: vCon});
+    outTask.exec(errWithMeta); //call the final callback with the first error hit
+  };
+}
+
+function findTasksReady(vCon, tasks, tasksByName) {
+  return tasks.filter(function (t) { return t.isReady(vCon, tasksByName); });
+}
+
+function execTasks(tasksReady, vCon, handleError, contExec) {
+  tasksReady.forEach(function (t) { t.status = STATUS.READY; }); //set ready first, no double exec
+  tasksReady.forEach(function (t) { t.exec(vCon, handleError, contExec); }); 
+}
+
+/**
+   this will be called if there are no tasks found to run,
+   and it will check if there are still tasks running or ready
+   (which means they will be running shortly), in which
+   case everything is fine. If no tasks are running then
+   call handleError since this will never complete.
+  */
+function checkIfTasksRunning(vCon, tasks, handleError) {
+  var tasksRunning = tasks.filter(function (t) {
+    return (t.status === STATUS.RUNNING || t.status === STATUS.READY);
+  });
+  if (!tasksRunning.length) handleError({}, new Error(NO_TASKS_RUNNING_WONT_COMPLETE));
+}
+
+function findReadyAndExec(vCon, tasks, tasksByName, handleError, contExec) {
+  var tasksReady = findTasksReady(vCon, tasks, tasksByName);
+  if (!tasksReady.length) checkIfTasksRunning(vCon, tasks, handleError); // no tasks to run, check if ok
+  execTasks(tasksReady, vCon, handleError, contExec);
+}
+
+function serializeTasks(tasks) { // conveniently set after for each task idx > 0
+  nameTasks(tasks);
+  tasks.forEach(function (t, idx, arr) { if (idx !== 0) t.after = [arr[idx - 1].name]; }); 
+  return tasks;
+}
+
+exports.serializeTasks = serializeTasks;
+
+exports.TASK_TYPES = TASK_TYPES;
+exports.taskTypeKeys = taskTypeKeys;
+exports.OUT_TASK_TYPES = OUT_TASK_TYPES;
+exports.outTaskTypeKeys = outTaskTypeKeys;
+exports.setMissingType = setMissingType;
+exports.validate = validate;
+exports.validateOutTask = validateOutTask;
+exports.validateLocalFunctions = validateLocalFunctions;
+exports.nameTasks = nameTasks;
+exports.create = create;
+exports.createOutTask = createOutTask;
+exports.createCallback = createCallback;
+exports.createErrorHandler = createErrorHandler;
+exports.findReadyAndExec = findReadyAndExec;

package/lib/validate.js

@@ -0,0 +1,102 @@
+'use strict';
+
+var util = require('util');
+var sprintf = require('sprintf').sprintf;
+var array = require('ensure-array');
+var tutil = require('./task.js');
+
+var AST_IS_OBJECT = 'ast must be an object with inParams, tasks, and outTask';
+var INPARAMS_ARR_STR = 'ast.inParams must be an array of strings';
+var TASKS_ARR = 'ast.tasks must be an array of tasks';
+var NAMES_UNIQUE = 'ast.tasks that specify name need to be unique, duplicate:';
+var LOCALS_NOTNULL = 'ast.locals should not be null';
+var DUP_OUTPUTS = 'multiple tasks output the same param, must be unique. param';
+
+var validateInParams, validateTasks, validateOutTask, validateTaskNamesUnique;
+var validateLocals, validateOuputsUnique;
+
+function format_error(errmsg, obj) {
+  return sprintf('%s - %s', errmsg, util.inspect(obj));
+}
+
+/**
+   validate the AST return Errors
+   @example
+   var validate = require('./validate');
+   var errors = validate(ast);
+   @returns array of errors, could be empty
+  */
+function validate(ast) {
+  if (!ast || !ast.inParams || !ast.tasks || !ast.outTask) return [AST_IS_OBJECT];
+  var errors = [];
+  errors = errors.concat(validateInParams(ast.inParams));
+  errors = errors.concat(validateTasks(ast.tasks));
+  errors = errors.concat(validateTaskNamesUnique(ast.tasks));
+  errors = errors.concat(tutil.validateOutTask(ast.outTask));
+  errors = errors.concat(validateLocals(ast.locals));
+  if (errors.length === 0) { // if no errors do additional validation
+    if (ast.outTask.type !== 'finalcbFirst') errors = errors.concat(validateOuputsUnique(ast.tasks));
+    errors = errors.concat(tutil.validateLocalFunctions(ast.inParams, ast.tasks, ast.locals));
+  }
+  return errors;
+}
+
+/**
+   @returns array of errors, could be empty
+ */
+function validateInParams(inParams) {
+  if (!Array.isArray(inParams) ||
+      !inParams.every(function (x) { return (typeof(x) === 'string'); })) {
+    return [INPARAMS_ARR_STR];
+  }
+  return [];
+}
+
+/**
+   @returns array of errors, could be empty
+ */
+function validateTasks(tasks) {
+  if (!Array.isArray(tasks)) return [TASKS_ARR];
+  var errors = [];
+  tasks.forEach(function (t) {
+    errors = errors.concat(tutil.validate(t));
+  });
+  return errors;
+}
+
+function validateTaskNamesUnique(tasks) {
+  if (!Array.isArray(tasks)) return [];
+  var errors = [];
+  var namedTasks = tasks.filter(function (t) { return (t.name); });
+  var names = namedTasks.map(function (t) { return t.name; });
+  names.reduce(function (accum, name) {
+    if (accum[name]) errors.push(sprintf('%s %s', NAMES_UNIQUE, name));
+    else accum[name] = true;
+    return accum;
+  }, {});                             
+  return errors;
+}
+
+function validateLocals(locals) {
+  var errors = [];
+  if (locals === null) errors.push(LOCALS_NOTNULL);
+  return errors;
+}
+
+function getOutputParams(taskDef) {
+  return array(taskDef.out); //ensure array
+}
+
+function validateOuputsUnique(taskDefs) {
+  var errors = [];
+  taskDefs.reduce(function (accum, t) {
+    getOutputParams(t).forEach(function (param) {
+      if (accum[param] !== undefined) errors.push(sprintf('%s: %s', DUP_OUTPUTS, param));
+      else accum[param] = true;
+    });
+    return accum;
+  }, {});
+  return errors;
+}
+
+module.exports = validate;

package/lib/vcon.js

@@ -0,0 +1,76 @@
+'use strict';
+
+var LAST_RESULTS_KEY = ':LAST_RESULTS';
+
+function VContext() {
+}
+
+VContext.prototype.getLastResults = function () { return this.getVar(LAST_RESULTS_KEY); };
+VContext.prototype.setLastResults = function (args) { this.setVar(LAST_RESULTS_KEY, args); };
+
+VContext.prototype.getVar = function (name) { //name might be simple or obj.prop, also literals
+  var vConValues = this.values;
+  if (typeof(name) !== 'string') return name; // literal boolean or number
+  name = name.trim();
+  if (name === 'true') return true;
+  if (name === 'false') return false;
+  if (/^-?[0-9]+$/.test(name)) return parseInt(name, 10); //int
+  if (/^-?[0-9.]+$/.test(name)) return parseFloat(name);  //float
+  var m = /^("|')([^\1]*)\1$/.exec(name);  //check for quoted string " or '
+  if (m) return m[2]; // if is quoted str, return inside of the quotes
+  var nameAndProps = name.split('.');
+  return nameAndProps.reduce(function (accObj, prop) {
+    if (accObj === undefined || accObj === null) return undefined; // prevent exception
+    return accObj[prop];
+  }, vConValues);   // vCon['foo']['bar']
+};
+
+/**
+   Saves all the results from a task as a unit, also sets special
+   variable :LAST_RESULTS which keeps an array of the last values
+   which can be used for chaining and testing last results, etc.
+  */
+VContext.prototype.saveResults = function(paramArr, valuesArr) { // set values for params
+  var self = this;
+  paramArr.forEach(function (k, idx) { //save values to v context
+    self.setVar(k, (valuesArr[idx] !== undefined) ? valuesArr[idx] : null); //upgrade any undefined to null
+  });
+  this.setLastResults(valuesArr);
+}
+
+VContext.prototype.setVar = function (name, value) { //name might be simple or obj.prop
+  if (!name) return;  // if name is undefined or null, then discard
+  var vConValues = this.values;
+  var nameAndProps = name.split('.');
+  var lastProp = nameAndProps.pop();
+  var obj = nameAndProps.reduce(function (accObj, prop) {
+    var o = accObj[prop];
+    if (o === undefined || o === null) {  // if doesn't exist create it
+      o = accObj[prop] = { };
+    }
+    return o;
+  }, vConValues);   // vCon['foo']['bar']
+  obj[lastProp] = value;
+};
+  
+
+/**
+   Create Variable Context using arguments passed in.
+   Ignore extra arguments passed in. Locals can be
+   passed into seed the VContext otherwise empty {}
+   will be used
+ */
+VContext.create = function (args, inParams, locals) {
+  var initValues = {};
+  if (locals) Object.keys(locals).forEach(function (k) { initValues[k] = locals[k]; }); // copy over keys
+  var vContext = new VContext();
+  vContext.values = args.reduce(function (vcon, x, idx) { // create vCon start with input args
+    var param = inParams[idx];
+    if (param) vcon[param] = x;
+    return vcon;
+  }, initValues);
+  return vContext;
+};
+
+
+module.exports = VContext;