react 0.0.3 → 0.1.2

package/lib/parse.js

@@ -0,0 +1,28 @@
+'use strict';
+
+var sprintf = require('sprintf').sprintf;
+
+function splitTrimFilterArgs(commaSepArgs) { //parse 'one, two' into ['one', 'two']
+  return commaSepArgs.split(',')            //split on commas
+    .map(function (s) { return s.trim(); }) //trim
+    .filter(function (s) { return (s); });  //filter out empty strings
+}
+
+function parseReduce(accum, regexFn) {
+  if (typeof(accum) !== 'string') return accum; // already matched
+  var m = regexFn.regex.exec(accum);
+  if (m) return regexFn.fn(m); // return result obj
+  return accum; // no match, return str, will try next matcher
+}
+
+function parseStr(str, parseMatchers, errStr) {
+  var result = parseMatchers.reduce(parseReduce, str);
+  if (typeof(result) !== 'string') { // matched
+    return result;
+  } else { // no match
+    throw new Error(sprintf(errStr, str));
+  }  
+}
+
+exports.splitTrimFilterArgs = splitTrimFilterArgs;
+exports.parseStr = parseStr;

package/lib/pcode.js

@@ -0,0 +1,164 @@
+'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, cb" -  found: %s';
+var OUTPARAMS_NO_MATCH = 'output params in wrong format, wanted "cb(err, foo)" - found: %s';
+var INOUT_PARAMS_NO_MATCH = 'task params in wrong format, wanted "foo, bar := func(baz, cat, cb) " - found: %s';
+var EXTRA_TASKARG = 'extra unmatched task arg: %s';
+
+/**
+  Examples:
+  var react = require('react');
+  
+  var locals = { falpha: falpha, fbeta: fbeta, fcharlie: fcharlie };
+  var fn = react.pcodeDefine('a, b', [
+    'd := fbeta(a, b)',
+    'e = fcharlie(a, b)',
+    'c := falpha(a, b) when fbeta:done and fcharlie:done',
+    'cb(err, c, d, e);'
+  ], locals);
+
+  function cb(err, d, e) { }
+  fn(10, 20, cb);
+ */
+
+function splitAndFilterArgs(commaSepArgs) { // split, trim, filter out empty and (cb or callback)
+  var args = parse.splitTrimFilterArgs(commaSepArgs);
+  var cbNamesRe = /^cb|callback$/i;  //cb, Cb, CB, callback, Callback
+  if (args.length && args[args.length - 1].match(cbNamesRe)) args.pop();
+  return args;
+}
+
+function extractNamesFromWhenClause(str) { //given 'foo:done and bar.baz:done' return ['foo', 'bar.baz']
+  var reSplit = /\s+and\s+/i;
+  var reDone = /^([^:]+):done$/i;
+  var names = str.split(reSplit).map(function (x) {
+    x = x.trim();
+    var m = x.match(reDone); // if foo:done, we'll use foo
+    return (m) ? m[1] : x; 
+  });
+  return names;
+}
+
+var inParse = {
+  regex: /^(.*)$/, 
+  fn: function (m) {
+    return {
+      inDef: splitAndFilterArgs(m[1]),
+    };
+  }
+};
+
+var cbParse = {
+  regex: /^\s*(var\s+)?([^:]*)\s*:=\s*([a-zA-Z0-9_\.-]+)\s*\(\s*([^)]*)\)\s*(when\s+([^;]+))?;?\s*$/,
+  fn: function (m) {
+    var taskDef = {
+      type: 'cb',
+      f: m[3],
+      inDef: (m[4]) ? splitAndFilterArgs(m[4]) : [],
+      outDef: (m[2]) ? parse.splitTrimFilterArgs(m[2]) : []
+    };
+    if (m[6]) taskDef.after = extractNamesFromWhenClause(m[6]);
+    return taskDef;
+  }
+};
+
+var retParse = {
+  regex: /^\s*(var\s+)?([^:]*)\s*=\s*([a-zA-Z0-9_\.-]+)\s*\(\s*([^)]*)\)\s*(when\s+([^;]+))?;?\s*$/,
+  fn: function (m) {
+    var taskDef = {
+      type: 'ret',
+      f: m[3],
+      inDef: (m[4]) ? splitAndFilterArgs(m[4]) : [],
+      outDef: (m[2]) ? parse.splitTrimFilterArgs(m[2]) : []
+    };
+    if (m[6]) taskDef.after = extractNamesFromWhenClause(m[6]);
+    return taskDef;
+  }
+};
+
+var finalCbParse = {
+  regex: /^\s*(cb|callback)\s*\((er{0,2}\s*,\s*)?([^)]*)\)\s*;?$/i,
+  fn: function (m) {
+    return {
+      outDef: (m[3]) ? parse.splitTrimFilterArgs(m[3]) : []
+    };
+  }
+};
+
+function parseInParams(str) {
+  return parse.parseStr(str, [inParse], INPARAMS_NO_MATCH);
+}
+
+function parseTask(str) {
+  var result = parse.parseStr(str, [cbParse, retParse], INOUT_PARAMS_NO_MATCH);
+  var type = result.type;
+  var task = {
+    f: result.f,
+    a: result.inDef
+  };
+  task.out = result.outDef;
+  task.type = type;
+  if (result.after) task.after = result.after;
+  return task;
+}
+
+function parseOutParams(str) {
+  if (!str.trim().length) return { outDef: [] };
+  return parse.parseStr(str, [finalCbParse], OUTPARAMS_NO_MATCH);
+} 
+
+function parseTasks(arr) { return arr.map(parseTask); }
+
+
+function pcodeDefine(inParamStr, taskStrArr, locals, options) {
+  if (!inParamStr) inParamStr = '';
+  if (!taskStrArr) taskStrArr = [];
+  var outTaskStr = (taskStrArr.length) ? taskStrArr.pop() : '';
+  if (!locals) locals = { };
+
+  var reactFn = core();
+  var ast = {
+    inParams: parseInParams(inParamStr).inDef,
+    tasks: parseTasks(taskStrArr),
+    outTask: { a: parseOutParams(outTaskStr).outDef },
+    locals: locals
+  };
+  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, taskStrArr, locals, options) {
+  if (!inParamStr) inParamStr = '';
+  if (!taskStrArr) taskStrArr = [];
+  var outTaskStr = (taskStrArr.length) ? taskStrArr.pop() : '';
+  if (!locals) locals = { };
+  var tasks = tutil.serializeTasks(parseTasks(taskStrArr));
+  
+  var reactFn = core();
+  var ast = {
+    inParams: parseInParams(inParamStr).inDef,
+    tasks: tasks,
+    outTask: { type: 'finalcbFirst', a: parseOutParams(outTaskStr).outDef },
+    locals: locals
+  };
+  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 = pcodeDefine;
+module.exports.selectFirst = selectFirst;

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;