react 0.2.6 → 0.5.0

package/lib/task.js

@@ -4,16 +4,21 @@ var util = require('util');
 var sprintf = require('sprintf').sprintf;
 var array = require('ensure-array');
 var CbTask = require('./cb-task.js');
+var PromiseTask = require('./promise-task.js');
 var RetTask = require('./ret-task.js');
+var WhenTask = require('./when-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 EventManager = require('./event-manager.js');
 
 var TASK_TYPES = {
   cb: CbTask,
-  ret: RetTask
+  ret: RetTask,
+  promise: PromiseTask,
+  when: WhenTask
 };
 function taskTypeKeys() { return Object.keys(TASK_TYPES); }
 
@@ -106,7 +111,8 @@ function validateLocalFunctions(inParams, taskDefs, locals) {
   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) {
+  var tasksWFunctions = tasks.filter(function (t) { return (t.type !== 'when'); }); // non-when tasks need f
+  tasksWFunctions.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 {
@@ -121,7 +127,9 @@ function validateLocalFunctions(inParams, taskDefs, locals) {
 }
 
 function fName(fn) {
-  return (typeof(fn) === 'string') ? fn : fn.name;
+  return (fn) ?
+    ((fn.name) ? fn.name : fn) :  // if defined, try name, otherwise toString()
+    'undefined';  // not defined, use undefined
 }
 
 /**
@@ -155,27 +163,28 @@ function create(taskDef) {
   return new TaskConstructor(taskDef);
 }
 
-function createOutTask(taskDef, cbFinal, tasks, vCon) {
+function createOutTask(taskDef, cbFunc, tasks, vCon, execOptions, env) {
   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();
+  var outTaskOptions = {
+    taskDef: taskDef,
+    cbFunc: cbFunc,
+    tasks: tasks,
+    vCon: vCon,
+    execOptions: execOptions,
+    env: env,
+    TaskConstructor: OUT_TASK_TYPES[taskDef.type]
   };
+  EventManager.global.emit(EventManager.TYPES.EXEC_OUTTASK_CREATE, outTaskOptions); // hook
+  var TaskConstructor = outTaskOptions.TaskConstructor;  // hook could have changed
+  return new TaskConstructor(outTaskOptions);
 }
-
+  
 function createErrorHandler(vCon, outTask) {
   return function handleError(task, err) {
     task.status = STATUS.ERRORED;
+    task.error = err;
+    outTask.env.currentTask = task;
+    outTask.env.flowEmitter.emit(EventManager.TYPES.EXEC_TASK_ERRORED, task);
     var errWithMeta = error.augmentError(err, {task: task, vcon: vCon});
     outTask.exec(errWithMeta); //call the final callback with the first error hit
   };
@@ -197,7 +206,7 @@ function execTasks(tasksReady, vCon, handleError, contExec) {
    case everything is fine. If no tasks are running then
    call handleError since this will never complete.
   */
-function checkIfTasksRunning(vCon, tasks, handleError) {
+function checkIfTasksRunning(vCon, tasks, handleError, env) {
   var tasksRunning = tasks.filter(function (t) {
     return (t.status === STATUS.RUNNING || t.status === STATUS.READY);
   });
@@ -205,13 +214,14 @@ function checkIfTasksRunning(vCon, tasks, handleError) {
     var remainingTasks = tasks.filter(function (t) { return (!t.status); });
     var remainingTNames = remainingTasks.map(function (t) { return t.name; });
     var errMsg = sprintf(NO_TASKS_RUNNING_WONT_COMPLETE, remainingTNames.join(', '));
-    handleError({}, new Error(errMsg));
+    var emptyTask = { env: env };
+    handleError(emptyTask, new Error(errMsg));
   }
 }
 
-function findReadyAndExec(vCon, tasks, tasksByName, handleError, contExec) {
+function findReadyAndExec(vCon, tasks, tasksByName, handleError, contExec, env) {
   var tasksReady = findTasksReady(vCon, tasks, tasksByName);
-  if (!tasksReady.length) checkIfTasksRunning(vCon, tasks, handleError); // no tasks to run, check if ok
+  if (!tasksReady.length) checkIfTasksRunning(vCon, tasks, handleError, env); // no tasks to run, check if ok
   execTasks(tasksReady, vCon, handleError, contExec);
 }
 
@@ -234,6 +244,5 @@ exports.validateLocalFunctions = validateLocalFunctions;
 exports.nameTasks = nameTasks;
 exports.create = create;
 exports.createOutTask = createOutTask;
-exports.createCallback = createCallback;
 exports.createErrorHandler = createErrorHandler;
 exports.findReadyAndExec = findReadyAndExec;

package/lib/track-tasks.js

@@ -0,0 +1,60 @@
+'use strict';
+
+/**
+   Track the tasks, start, complete, args, results, elapsed time
+   Emits events that can be monitored
+
+    - track start and complete
+    - record args each task was called with
+    - record results at completion
+    - record start, end, and calc elapsed time
+    - emits flow.begin with flowEnv
+    - emits task.begin with task
+    - emits task.complete with task
+    - emits flow complete with flowEnv
+    - emits flow errored with flowEnv
+
+    @example
+    var react = require('react');
+    react.trackTasks(); // enable task and flow tracking
+  */
+
+
+var react = require('../');  // require('react');
+
+react.events.on(react.events.TYPES.EXEC_FLOW_START, function (env){
+  env.startTime = Date.now();
+  env.flowEmitter.emit(react.events.TYPES.FLOW_BEGIN, env); //fire public ev
+});
+
+react.events.on(react.events.TYPES.EXEC_TASK_START, function (task) {
+  task.startTime = Date.now();
+  task.env.flowEmitter.emit(react.events.TYPES.TASK_BEGIN, task); //fire public ev
+});
+
+react.events.on(react.events.TYPES.EXEC_TASK_COMPLETE, function (task) {
+  task.endTime = Date.now();
+  task.elapsedTime = task.endTime - task.startTime;
+  task.env.flowEmitter.emit(react.events.TYPES.TASK_COMPLETE, task); // fire public ev
+});
+
+react.events.on(react.events.TYPES.EXEC_TASK_ERRORED, function (task) {
+  task.endTime = Date.now();
+  task.elapsedTime = task.endTime - task.startTime;
+  task.env.flowEmitter.emit(react.events.TYPES.TASK_ERRORED, task); // fire public ev
+});
+
+react.events.on(react.events.TYPES.EXEC_FLOW_COMPLETE, function (env) {
+  env.endTime = Date.now();
+  env.elapsedTime = env.endTime - env.startTime;
+  env.flowEmitter.emit(react.events.TYPES.FLOW_COMPLETE, env); //fire public ev
+});
+
+react.events.on(react.events.TYPES.EXEC_FLOW_ERRORED, function (env) {
+  env.endTime = Date.now();
+  env.elapsedTime = env.endTime - env.startTime;
+  env.flowEmitter.emit(react.events.TYPES.FLOW_ERRORED, env); //fire public ev
+});
+
+
+module.exports = react;  // return react

package/lib/validate.js

@@ -13,8 +13,8 @@ var LOCALS_NOTNULL = 'ast.locals should not be null';
 var DUP_OUTPUTS = 'multiple tasks output the same param, must be unique. param';
 var MISSING_INPUTS = 'missing or mispelled variable referenced in flow definition: %s';
 
-// match any of our literals true, false, int, float, quoted strings, or is property (has dot)
-var LITERAL_OR_PROP_RE = /^(true|false|\-?[0-9\.]+)$|'|"|\./i;  
+// match any of our literals true, false, int, float, quoted strings, or is property (has dot), match vcon.js
+var LITERAL_OR_PROP_RE = /^(true|false|this|null|\-?[0-9\.]+)$|'|"|\./i;  
 
 var validateInParams, validateTasks, validateOutTask, validateTaskNamesUnique;
 var validateLocals, validateOuputsUnique, validateNoMissingNames;
@@ -153,7 +153,7 @@ function validateNoMissingNames(ast) {
     if (!isLiteralOrProp(p) && !names[p]) accum.push(sprintf(MISSING_INPUTS, p)); // add error if missing
     return accum;
   }, errors);
-  return errors;  //TODO reenable
+  return errors;  
 }
 
 module.exports = validate;

package/lib/vcon.js

@@ -16,6 +16,7 @@ VContext.prototype.getVar = function (name) { //name might be simple or obj.prop
   // literal checks need to match what is in validate.js
   if (name === 'true') return true;
   if (name === 'false') return false;
+  if (name === 'null') return null;
   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 '
@@ -32,13 +33,13 @@ VContext.prototype.getVar = function (name) { //name might be simple or obj.prop
    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
+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
@@ -61,9 +62,11 @@ VContext.prototype.setVar = function (name, value) { //name might be simple or o
    Ignore extra arguments passed in. Locals can be
    passed into seed the VContext otherwise empty {}
    will be used
+   @param self used to pass 'this' context in
  */
-VContext.create = function (args, inParams, locals) {
+VContext.create = function (args, inParams, locals, self) {
   var initValues = {};
+  if (self) initValues['this'] = self;
   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

package/lib/when-task.js

@@ -0,0 +1,81 @@
+'use strict';
+
+/**
+   When task which checks if is a promise (has a then method)
+   and waits for it to resolve.
+
+   If argument does not have a then method, it resolves immediately
+  */
+
+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 = 'whenTask requires a, out';
+var A_REQ = 'whenTask requires a to be an array[1] of string param names';
+var OUT_REQ = 'whenTask requires out to be an array[1] of string param names';
+
+function WhenTask(taskDef) {
+  var self = this;
+  Object.keys(taskDef).forEach(function (k) { self[k] = taskDef[k]; });
+}
+
+WhenTask.prototype = new BaseTask();
+WhenTask.prototype.constructor = WhenTask;
+
+WhenTask.prototype.f = function when() { // just here to keep validations happy 
+}
+
+WhenTask.validate = function (taskDef) {
+  var errors = [];
+  if (!taskDef.a || !taskDef.out) {
+    errors.push(format_error(REQ, taskDef));
+  } else {
+    if (! (Array.isArray(taskDef.a) && taskDef.a.length === 1 && 
+           taskDef.a.every(function (x) { return (typeof(x) === 'string'); }))) {
+      errors.push(format_error(A_REQ, taskDef));
+    }
+    if (! (Array.isArray(taskDef.out) && taskDef.out.length <= 1 && 
+           taskDef.out.every(function (x) { return (typeof(x) === 'string'); }))) {
+      errors.push(format_error(OUT_REQ, taskDef));
+    }
+  }
+  return errors;
+};
+
+WhenTask.prototype.prepare = function prepare(handleTaskError, vCon, contExec) {
+  var self = this;
+  this.nextFn = function (arg) {
+    var args = Array.prototype.slice.call(arguments);
+    vCon.saveResults(self.out, args);
+    self.complete(args);
+    contExec();
+  };
+  this.failFn = function (err) {
+    handleTaskError(self, err);
+  };
+};
+
+WhenTask.prototype.exec = function exec(vCon, handleError, contExec) {
+  try {
+    var args = this.a.map(function (k) { return vCon.getVar(k); }); //get args from vCon
+    //console.error('WhenTask.exec.args=', args);
+    //console.error('WhenTask.exec.vCon=', vCon);
+    this.start(args); //note the start time, args
+    var arg = args[0]; // one value allowed
+    if (arg && typeof(arg.then) === 'function') { // is a promise
+      arg.then(this.nextFn, this.failFn);
+    } else { // not a promise continue immediately
+      this.nextFn(arg);
+    }
+  } catch (err) { //catch and handle the task error, calling final cb
+    handleError(this, err);
+  } 
+};
+
+module.exports = WhenTask;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "react",
-  "description": "React is a javascript module to make it easier to work with asynchronous code, by reducing boilerplate code and improving error and exception handling while allowing variable and task dependencies when defining flow.",
-  "version": "0.2.6",
+  "description": "React is a javascript module implementing a lightweight rules engine to make it easier to work with asynchronous code, by reducing boilerplate code and improving error and exception handling while allowing variable and task dependencies when defining flow.",
+  "version": "0.5.0",
   "author": "Jeff Barczewski <jeff.barczewski@gmail.com>",
   "repository": { "type": "git", "url": "http://github.com/jeffbski/react.git" },
   "bugs" : { "url": "http://github.com/jeffbski/react/issues" },
@@ -15,7 +15,9 @@
   },
   "devDependencies": {
     "tap" : "~0.1.0",
-    "tapr" : "~0.1.0"
+    "tapr" : "~0.1.0",
+    "promised-io" : "~0.3.0",
+    "Deferred" : "~0.1.1"
   },
   "scripts": {
     "test": "node_modules/.bin/tapr test"

package/react.js

@@ -2,11 +2,39 @@
 
 var core = require('./lib/core.js');
 
+/**
+   If called, load the built-in plugin for log events and invoke
+
+   @param flowFn [function] if not provided uses global react
+   @param eventWildcard [string] pattern to log events for
+  */
+function logEvents(flowFn, eventWildcard) {
+  var logEventsMod = require('./lib/log-events');
+  if (!eventWildcard && typeof(flowFn) === 'string') { // only wildcard provided
+    eventWildcard = flowFn;
+    flowFn = undefined;
+  } 
+  return logEventsMod.logEvents(flowFn, eventWildcard);
+}
+
+/**
+   Enable detection of promises and resolution
+  */
+function resolvePromises() {
+  require('./lib/promise-resolve');
+}
+
+/**
+   Enable tracking of tasks and flow execution, emitting events and
+   tracking start, end, elapsed time
+  */
+function trackTasks() {
+  require('./lib/track-tasks');
+}
+
 module.exports = require('./lib/dsl.js');  // core + default dsl
 module.exports.options = core.options; // global react options
 module.exports.events = core.events;   // global react event emitter
-
-// additional interfaces
-module.exports.fstrDefine = require('./lib/fstr.js');
-module.exports.pcodeDefine = require('./lib/pcode.js');
-module.exports.chainDefine = require('./lib/chain.js');
+module.exports.logEvents = logEvents;  // enable event logging
+module.exports.resolvePromises = resolvePromises; // enable promise resolution
+module.exports.trackTasks = trackTasks; // enable tracking of tasks

package/test/core-deferred.test.js

@@ -0,0 +1,134 @@
+'use strict';
+
+/**
+   Test core PromiseTasks using Deferred - jquery style promises
+  */
+
+
+var test = require('tap').test;
+var Deferred = require('Deferred');
+//var when = Deferred.when;
+
+
+var react = require('../');  //require('react');
+
+function multiply(x, y) {
+  var deferred = new Deferred();
+  setTimeout(function () {
+    deferred.resolve(x * y);
+  }, 10);
+  return deferred.promise();
+}
+function add(x, y) {
+  var deferred = new Deferred();
+  setTimeout(function () {
+    deferred.resolve(x + y);
+  }, 10);
+  return deferred.promise();
+}
+
+function badFunc(a, b) {
+  throw new Error('badFuncThrow');
+}
+
+function badF2(a, b) {
+  var deferred = new Deferred();
+  setTimeout(function () {
+    deferred.reject(new Error('my-error'));
+  }, 10);
+  return deferred.promise();
+}
+
+
+test('multi-step', function (t) {
+  t.plan(4);
+  var fn = react();
+  var errors = fn.setAndValidateAST({
+    inParams: ['a', 'b'],
+    tasks: [    
+      { f: multiply, a: ['a', 'b'], out: ['c'], type: 'promise' },
+      { f: add, a: ['c', 'b'], out: ['d'], type: 'promise' }
+    ],
+    outTask: { a: ['c', 'd'] }
+  });
+  t.deepEqual(errors, [], 'no validation errors');
+
+  fn(2, 3, function (err, c, d) {
+    t.equal(err, null);
+    t.equal(c, 6);
+    t.equal(d, 9);
+    t.end();
+  });
+});  
+
+test('using "this" in a cb function', function (t) {
+  t.plan(3);
+  function getA(cb) {
+    /*jshint validthis: true */
+    var deferred = new Deferred();
+    var self = this;
+    setTimeout(function () {
+      deferred.resolve(self.a);
+    }, 10);
+    return deferred.promise();
+  }
+  
+  var fn = react();
+  var errors = fn.setAndValidateAST({
+    inParams: [],
+    tasks: [    
+      { f: getA, a: [], out: ['a'], type: 'promise' }
+    ],
+    outTask: { a: ['a'] }
+  });
+  t.deepEqual(errors, [], 'no validation errors');
+
+  var obj = {
+      a: 100
+  };
+
+  fn.apply(obj, [function (err, a) {
+    t.equal(err, null);
+    t.equal(a, 100);
+    t.end();
+  }]);
+});
+
+
+test('throws error', function (t) {
+  t.plan(2);
+  var fn = react();
+  var errors = fn.setAndValidateAST({
+    inParams: ['a', 'b'],
+    tasks: [    
+      { f: badFunc, a: ['a', 'b'], out: ['c'], type: 'promise' },
+      { f: add, a: ['c', 'b'], out: ['d'], type: 'promise' }
+    ],
+    outTask: { a: ['c', 'd'] }
+  });
+  t.deepEqual(errors, [], 'no validation errors');
+
+  fn(2, 3, function (err, c, d) {
+    t.equal(err.message, 'badFuncThrow');
+    t.end();
+  });
+});
+
+test('rejects with error', function (t) {
+  t.plan(2);
+  var fn = react();
+  var errors = fn.setAndValidateAST({
+    inParams: ['a', 'b'],
+    tasks: [    
+      { f: badF2, a: ['a', 'b'], out: ['c'], type: 'promise' },
+      { f: add, a: ['c', 'b'], out: ['d'], type: 'promise' }
+    ],
+    outTask: { a: ['c', 'd'] }
+  });
+  t.deepEqual(errors, [], 'no validation errors');
+
+  fn(2, 3, function (err, c, d) {
+    t.equal(err.message, 'my-error');
+    t.end();
+  });
+});