react 0.2.6 → 0.5.0

package/doc/default-simple.dot

@@ -0,0 +1,19 @@
+digraph simple {
+  inputs [shape=box];
+  loadFoo [shape=box];
+  loadBar [shape=box];
+  render [shape=box];
+  outputs[shape=box];
+  inputs -> fooPath;
+  inputs -> barPath;
+  inputs -> barP2;
+  fooPath -> loadFoo;
+  loadFoo -> foo;
+  barPath -> loadBar;
+  loadBar -> bar;
+  barP2 -> loadBar;
+  foo -> render;
+  bar -> render;
+  render -> renderedOut;
+  renderedOut -> outputs;
+}

package/examples/default-events1.js

@@ -1,22 +1,49 @@
 'use strict';
 /*jshint white: false */
 
+/**
+   Default DSL, showing use of events
+  */
+
 var react = require('../'); // require('react');
+require('../lib/track-tasks');  // require('react/lib/track-tasks'); // turn on tracking
 
 //output events as tasks start and complete
-react.events.on('*', function (obj) {
+react.events.on('flow.*', function (obj) {
+  /*jshint validthis: true */
   var time = new Date();
   time.setTime(obj.time);
+  var argsNoCb = obj.args.filter(function (a) { return (typeof(a) !== 'function'); });
   var eventTimeStr = time.toISOString();
+  if (this.event === 'flow.complete') {
+    var env = obj; 
+    console.error('%s: %s \tmsecs:(%s) \n\targs:(%s) \n\tresults:(%s)\n',
+                  this.event, env.name, env.elapsedTime, argsNoCb, env.results);   
+  } else {
+    var name = obj.name;
+    var args = obj.args;
+    console.error('%s: %s \n\targs:(%s)\n', this.event, name, argsNoCb);
+  }
+});
+
+react.events.on('task.*', function (obj) {
+  /*jshint validthis: true */
+  var time = new Date();
+  time.setTime(obj.time);
   var argsNoCb = obj.args.filter(function (a) { return (typeof(a) !== 'function'); });
-  if (obj.event === 'task.complete') {
+  var eventTimeStr = time.toISOString();
+  if (this.event === 'task.complete') {
+    var task = obj;
     console.error('%s: %s \tmsecs:(%s) \n\targs:(%s) \n\tresults:(%s)\n',
-                  obj.event, obj.name, obj.elapsedTime, argsNoCb, obj.results);
+                  this.event, task.name, task.elapsedTime, argsNoCb, task.results);
   } else {
-    console.error('%s: %s \n\targs:(%s)\n', obj.event, obj.name, argsNoCb);
+    var name = obj.name;
+    var args = obj.args;
+    console.error('%s: %s \n\targs:(%s)\n', this.event, name, argsNoCb);
   }
 });
-                
+
+
 
 function loadUser(uid, cb){ setTimeout(cb, 100, null, "User"+uid); }
 function loadFile(filename, cb){ setTimeout(cb, 100, null, 'Filedata'+filename); }
@@ -43,7 +70,7 @@ var loadAndSave = react('loadAndSave', 'filename, uid, outDirname, cb -> err, ht
   writeOutput,      'html, user, cb   -> err, bytesWritten', { after: prepareDirectory },  // only after prepareDirectory done
   loadEmailTemplate, 'cb              -> err, emailmd',
   markdown,         'emailmd          -> emailHtml',   // using a sync function
-  customizeEmail,   'user, emailHtml  -> err, custEmailHtml', // sync fn
+  customizeEmail,   'user, emailHtml  -> custEmailHtml', // sync fn
   deliverEmail,     'custEmailHtml, cb -> err, deliveredEmail', { after: writeOutput }  // only after writeOutput is done
 );
 

package/examples/{fstr1.js → default-log-events.js}

@@ -1,6 +1,13 @@
 'use strict';
+/*jshint white: false */
+
+/**
+   Default DSL, showing use of events
+  */
 
 var react = require('../'); // require('react');
+react.logEvents(); // turn on logging of all flow and task events for all react functions
+
 
 function loadUser(uid, cb){ setTimeout(cb, 100, null, "User"+uid); }
 function loadFile(filename, cb){ setTimeout(cb, 100, null, 'Filedata'+filename); }
@@ -8,28 +15,28 @@ function markdown(filedata) { return 'html'+filedata; }
 function prepareDirectory(outDirname, cb){ setTimeout(cb, 200, null, 'dircreated-'+outDirname); }
 function writeOutput(html, user, cb){  setTimeout(cb, 300, null, html+'_bytesWritten'); }
 function loadEmailTemplate(cb) { setTimeout(cb, 50, null, 'emailmd'); }
-function customizeEmail(user, emailHtml, cb) { return 'cust-'+user+emailHtml; }
+function customizeEmail(user, emailHtml) { return 'cust-'+user+emailHtml; }
 function deliverEmail(custEmailHtml, cb) { setTimeout(cb, 100, null, 'delivered-'+custEmailHtml); }
 
 function useHtml(err, html, user, bytesWritten) {
-  if(err) {
+  if (err) {
     console.log('***Error: %s', err);
     return;
   }
   console.log('final result: %s, user: %s, written:%s', html, user, bytesWritten);
 }
 
-var loadAndSave = react.fstrDefine('filename, uid, outDirname, cb', [  // input params
-  loadUser,         'uid              -> err, user',     // calling async fn loadUser with uid, callback is called with err and user
-  loadFile,         'filename         -> err, filedata',
-  markdown,         'filedata         -> returns html',    // using a sync function
-  prepareDirectory, 'outDirname       -> err, dircreated',
-  writeOutput,      'html, user       -> err, bytesWritten', { after: prepareDirectory },  // only after prepareDirectory done
-  loadEmailTemplate, '                 -> err, emailmd',
-  markdown,         'emailmd          -> returns emailHtml',   // using a sync function
-  customizeEmail,   'user, emailHtml  -> returns custEmailHtml',
-  deliverEmail,     'custEmailHtml    -> err, deliveredEmail', { after: writeOutput }  // only after writeOutput is done
-], 'err, html, user, bytesWritten');   // callback output params
+var loadAndSave = react('loadAndSave', 'filename, uid, outDirname, cb -> err, html, user, bytesWritten',  // name, in/out params
+  loadUser,         'uid, cb          -> err, user',     // calling async fn loadUser with uid, callback is called with err and user
+  loadFile,         'filename, cb     -> err, filedata',
+  markdown,         'filedata         -> html',    // using a sync function
+  prepareDirectory, 'outDirname, cb   -> err, dircreated',
+  writeOutput,      'html, user, cb   -> err, bytesWritten', { after: prepareDirectory },  // only after prepareDirectory done
+  loadEmailTemplate, 'cb              -> err, emailmd',
+  markdown,         'emailmd          -> emailHtml',   // using a sync function
+  customizeEmail,   'user, emailHtml  -> custEmailHtml', // sync fn
+  deliverEmail,     'custEmailHtml, cb -> err, deliveredEmail', { after: writeOutput }  // only after writeOutput is done
+);
 
 loadAndSave('file.md', 100, '/tmp/foo', useHtml);  // executing the flow
 

package/examples/default-simple.js

@@ -0,0 +1,45 @@
+'use strict';
+
+/**
+   Simple example showing flow definition of two async functions feeding a
+   synchronous function.
+
+   First two async functions inputs are satisfied by the flow inputs, so
+   they will both run immediately in parallel.
+
+   The last function waits for the outputs of the previous ones, then
+   executes synchronously.
+
+   Finally the flow calls the callback with the output values once all
+   the tasks have completed.
+  */
+
+var react = require('../'); // require('react');
+
+function loadFoo(fooPath, cb) {
+  setTimeout(function () {
+    cb(null, [fooPath, 'data'].join(':'));
+  }, 10);
+}
+
+function loadBar(barPath, barP2, cb) {
+  setTimeout(function () {
+    cb(null, [barPath, barP2, 'data'].join(':'));
+  }, 10);
+}
+
+function render(foo, bar) {
+  return ['<html>', foo, '/', bar, '</html>'].join('');
+}
+
+
+var fn = react('loadRender', 'fooPath, barPath, barP2, cb -> err, renderedOut',
+  loadFoo, 'fooPath, cb -> err, foo',
+  loadBar, 'barPath, barP2, cb -> err, bar',
+  render, 'foo, bar -> renderedOut'
+);
+
+
+fn('foo.txt', 'bar.txt', 'BBB', function (err, renderedOut) {
+  console.error('results:', renderedOut);
+});

package/lib/base-task.js

@@ -19,17 +19,18 @@ BaseTask.prototype.isComplete = function () {
 };
 
 BaseTask.prototype.start = function (args) { // mark task as started with args and note time
+  /*jshint validthis: true */
   this.args = args;
-  this.startTime = Date.now();
-  if (this.flowEmitter) this.flowEmitter.emitObject(EventManager.TYPES.TASK_BEGIN, this);
+  this.env.currentTask = this;
+  this.env.flowEmitter.emit(EventManager.TYPES.EXEC_TASK_START, this);
 };
 
 BaseTask.prototype.complete = function (args) { //args that were used are available
-  this.results = args;  // save the results
-  this.endTime = Date.now();
-  this.elapsedTime = this.endTime - this.startTime;
-  if (this.flowEmitter) this.flowEmitter.emitObject(EventManager.TYPES.TASK_COMPLETE, this);
+/*jshint validthis: true */
   this.status = STATUS.COMPLETE;
+  this.results = args;
+  this.env.currentTask = this;
+  this.env.flowEmitter.emit(EventManager.TYPES.EXEC_TASK_COMPLETE, this);
 };
 
 BaseTask.prototype.functionExists = function (vCon) {
@@ -96,6 +97,7 @@ BaseTask.prototype.isReady = function (vCon, tasksByName) {
 };
 
 BaseTask.prototype.isMethodCall = function () {
+  /*jshint regexp: false */
   return (typeof(this.f) === 'string' && /^.*\..*$/.test(this.f));  //str contains .
 };
 

package/lib/cb-task.js

@@ -43,6 +43,19 @@ CbTask.validate = function (taskDef) {
   return errors;
 };
 
+CbTask.prototype.prepare = function prepare(handleTaskError, vCon, contExec) {
+  var self = this;
+  this.cbFun = function (err, arg0, arg1, argn) {
+    var args = Array.prototype.slice.call(arguments, 1);
+    if (err) { handleTaskError(self, err); return; } //handle error and return, we are done
+
+    //no error, save callback args to vCon context, then continue execution
+    vCon.saveResults(self.out, args);
+    self.complete(args);
+    contExec();
+  };    
+};
+
 CbTask.prototype.exec = function exec(vCon, handleError, contExec) {
   try {
     var args = this.a.map(function (k) { return vCon.getVar(k); }); //get args from vCon
@@ -51,7 +64,7 @@ CbTask.prototype.exec = function exec(vCon, handleError, contExec) {
     this.start(args); //note the start time, args
     args.push(this.cbFun);   // push callback fn on end
     var func = this.f;
-    var bindObj = null; //global space
+    var bindObj = vCon.getVar('this'); //global space or the original this
     if (this.isMethodCall()) { //if method call then reset func and bindObj
       func = vCon.getVar(this.f);
       bindObj = this.getMethodObj(vCon);

package/lib/core.js

@@ -7,7 +7,6 @@ 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');
@@ -16,7 +15,17 @@ var reactOptions = {
   stackTraceLimitMin: 30
 };
 
-var reactEmitter = EventManager.globalEventManager; // the top emitter
+var reactEmitter = EventManager.global; // the top emitter
+
+/**
+   merge global react options with parsed options
+  */
+function mergeOptions(parsedOptions) {
+  return Object.keys(reactOptions).reduce(function (accum, k) {
+    if (!accum[k]) accum[k] = reactOptions[k];
+    return accum;
+  }, parsedOptions);    
+}
 
 /**
    Creates react function which the AST can be manipulated and then
@@ -56,32 +65,54 @@ function reactFactory() {
     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
+    if (Object.freeze) { //lets freeze the AST so plugin writers don't accidentally manip the ast
+      Object.keys(newAST).forEach(function (k) {
+        if (typeof(newAST[k]) === 'object') Object.freeze(newAST[k]);
+      });
+      Object.freeze(newAST);
+    }
     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);
+    /*jshint validthis: true */
+    var args = Array.prototype.slice.call(arguments);
+    var env = {
+      execId: idGenerator.createUniqueId(),
+      args: args,
+      ast: ast,
+      flowEmitter: flowEmitter
+    };
+    env.name = ast.name || env.execId;
+    flowEmitter.emit(EventManager.TYPES.EXEC_FLOW_START, env);  // hook
+    var parsedInput = inputParser(args, ast);
+    var vCon = VContext.create(parsedInput.args, ast.inParams, ast.locals, this); // create var ctx with in args & locals
+
+    env.parsedInput = parsedInput;
+    env.options = mergeOptions(parsedInput.options);
+    env.vCon = vCon;
+    env.taskDefs = ast.tasks.slice(); // create copy
+    env.outTaskDef = Object.create(ast.outTask); // create copy
+    reactEmitter.emit(EventManager.TYPES.EXEC_TASKS_PRECREATE, env);  // hook
+    
+    var tasks = env.taskDefs.map(tskutil.create);
     var tasksByName = tskutil.nameTasks(tasks); // map names to working tasks
-    var outTask = tskutil.createOutTask(ast.outTask, cbFinal, tasks, vCon);
+    var outTask = tskutil.createOutTask(env.outTaskDef, parsedInput.cb, tasks, vCon, env.options, env);
     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
+      tskutil.findReadyAndExec(vCon, tasks, tasksByName, handleError, contExec, env);  //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);
+      t.env = env;
+      if (t.prepare) t.prepare(handleError, vCon, contExec, flowEmitter);
     }); // create callbacks
     contExec();   // start things off
+    return outTask.retValue; // could return promise
   }
 
   var reactFn = exec;        // make the exec() the function returned

package/lib/dsl.js

@@ -6,8 +6,10 @@ var core = require('./core.js');
 var parse = require('./parse.js');
 var tutil = require('./task.js');
 
-var MISSING_NAME = 'param[0] should be the flow name, instead found in/out def: %s';
-var INOUT_PARAMS_NO_MATCH = 'params in wrong format, wanted "foo, bar cb -> err, baz" - found: %s';
+var MISSING_NAME = 'first flow parameter should be the flow name, but found in/out def: %s';
+var INOUT_PARAMS_NO_MATCH = 'params in wrong format, wanted "foo, bar, cb -> err, baz" - found: %s';
+var MISSING_ERR = 'callback specified, but first out param was not "err", use for clarity. Found in/out def: %s';
+var MISSING_CB = 'found err param, but cb/callback is not specified, is this cb-style async or sync function? Found in/out def: %s';
 var EXTRA_TASKARG = 'extra unmatched task arg: %s';
 
 var INOUT_RE = /\->/;  // used to detect missing name, in/out as first arg
@@ -25,12 +27,18 @@ function filterOutLeadingErrParam(args) { // if leading err param, filter it out
 }
 
 var inOutDefParse = {
-  regex: /^([^\-]*)(->\s*(.*))?$/i,
-  fn: function (m) {
-    var inParams = parse.splitTrimFilterArgs(m[1]);
+  splitStr: '->',
+  fn: function (m, origStr) {
+    var inParams = parse.splitTrimFilterArgs(m[0]);
     var lastParam = inParams[inParams.length - 1];
     var type = (lastParam && CB_NAMES_RE.test(lastParam)) ? 'cb' : 'ret';
-    var outParams = parse.splitTrimFilterArgs(m[3]);
+    var outParams = parse.splitTrimFilterArgs(m[1]);
+    var firstOutParam = outParams[0];
+    if (type === 'cb' && (!firstOutParam || !ERR_NAMES_RE.test(firstOutParam))) {
+      throw new Error(sprintf(MISSING_ERR, origStr));  // found cb, but no err param
+    } else if (type === 'ret' && firstOutParam && ERR_NAMES_RE.test(firstOutParam)) {
+      throw new Error(sprintf(MISSING_CB, origStr));  // found err but not cb param
+    }
     return {
       type: type,
       inDef: filterOutTrailingCbParam(inParams),

package/lib/event-collector.js

@@ -0,0 +1,65 @@
+'use strict';
+
+var react = require('../');  // require('react');
+react.trackTasks(); // enable task tracking
+
+var TASK_EVENTS_RE = /^task\./;
+var FLOW_EVENTS_RE = /^flow\./;
+
+/**
+   Accumulator to make it easy to capture events
+
+   @example
+   var EventCollector = require('react/lib/event-collector');
+   var collector = new EventCollector();
+
+   collector.capture(); // capture all flow and task events for all react flows
+   collector.capture('flow.*'); // capture all flow events for all react flows
+   collector.capture(flowFn, 'task.*'); // capture task events on a flow
+   collector.capture(flowFn, 'flow.*'); // add capture flow events on a flow
+
+   var events = collector.list();  // retrieve the list of events
+   collector.clear();  // clear the list of events;
+*/
+function EventCollector() {
+  this.events = [];
+}
+
+/**
+   register listener to capture events for a specific flow
+   @param flowFn the react flow function or can pass global react
+   @param eventId event id or wildcarded id
+  */
+EventCollector.prototype.capture = function (flowFn, eventId) {
+  /*jshint validthis: true */
+  if (!eventId && typeof(flowFn) === 'string') { // only eventId provided
+    eventId = flowFn;
+    flowFn = react; // global react
+  } else if (!flowFn) flowFn = react; // global react
+  if (!eventId) eventId = '*'; // default to all
+  var emitter = flowFn.events;
+  var self = this;
+  function accumEvents(obj) {
+    var eventObject = {
+      event: this.event,
+      time: Date.now()
+    };
+    if (FLOW_EVENTS_RE.test(this.event)) {
+      eventObject.env = obj;
+    } else if (TASK_EVENTS_RE.test(this.event)) {
+      eventObject.task = obj;
+    }
+    self.events.push(eventObject);      
+  }
+  emitter.on(eventId, accumEvents);
+};
+
+EventCollector.prototype.list = function () {
+  return this.events;
+};
+
+EventCollector.prototype.clear = function () {
+  this.events = []; // clear
+};
+
+module.exports = EventCollector;