react 0.3.0 → 0.3.4

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('task.*', 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); }

package/examples/default-log-events.js

@@ -0,0 +1,43 @@
+'use strict';
+/*jshint white: false */
+
+/**
+   Default DSL, showing use of events
+  */
+
+var react = require('../'); // require('react');
+require('../lib/log-events').logEvents(react);  // require('react/lib/log-events').logEvents(react); // turn on logging
+
+
+function loadUser(uid, cb){ setTimeout(cb, 100, null, "User"+uid); }
+function loadFile(filename, cb){ setTimeout(cb, 100, null, 'Filedata'+filename); }
+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) { return 'cust-'+user+emailHtml; }
+function deliverEmail(custEmailHtml, cb) { setTimeout(cb, 100, null, 'delivered-'+custEmailHtml); }
+
+function useHtml(err, html, user, bytesWritten) {
+  if (err) {
+    console.log('***Error: %s', err);
+    return;
+  }
+  console.log('final result: %s, user: %s, written:%s', html, user, bytesWritten);
+}
+
+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/fstr-events1.js

@@ -2,21 +2,7 @@
 /*jshint white: false */
 
 var fstr = require('../dsl/fstr'); // require('react/dsl/fstr');
-
-//output events as tasks start and complete
-fstr.events.on('task.*', function (obj) {
-  var time = new Date();
-  time.setTime(obj.time);
-  var eventTimeStr = time.toISOString();
-  var argsNoCb = obj.args.filter(function (a) { return (typeof(a) !== 'function'); });
-  if (obj.event === 'task.complete') {
-    console.error('%s: %s \tmsecs:(%s) \n\targs:(%s) \n\tresults:(%s)\n',
-                  obj.event, obj.name, obj.elapsedTime, argsNoCb, obj.results);
-  } else {
-    console.error('%s: %s \n\targs:(%s)\n', obj.event, obj.name, argsNoCb);
-  }
-});
-                
+require('../lib/log-events').logEvents(fstr); // require('react/lib/log-events').logEvents(react);
 
 function loadUser(uid, cb){ setTimeout(cb, 100, null, "User"+uid); }
 function loadFile(filename, cb){ setTimeout(cb, 100, null, 'Filedata'+filename); }

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) {

package/lib/core.js

@@ -76,32 +76,39 @@ function reactFactory() {
 
   function exec(arg1, arg2, argN, cb) { // called to execute the flow
     /*jshint validthis: true */
-    var parsedInput = inputParser(Array.prototype.slice.call(arguments), ast);
+    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
 
-    var taskEnv = { // collect taskEnv for hook
-      parsedInput: parsedInput,
-      vCon: vCon,
-      ast: ast,  // for reference, will not be used further
-      taskDefs: ast.tasks.slice(), // create copy
-      outTaskDef: ast.outTask
-    };    
-    reactEmitter.emit(EventManager.TYPES.EXEC_TASKS_PRECREATE, taskEnv);  // hook
+    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 = taskEnv.taskDefs.map(tskutil.create);
+    var tasks = env.taskDefs.map(tskutil.create);
     var tasksByName = tskutil.nameTasks(tasks); // map names to working tasks
-    var outTask = tskutil.createOutTask(taskEnv.outTaskDef, parsedInput.cb, tasks, vCon, mergeOptions(parsedInput.options));
+    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;
+      t.env = env;
       if (t.prepare) t.prepare(handleError, vCon, contExec, flowEmitter);
     }); // create callbacks
     contExec();   // start things off

package/lib/event-manager.js

@@ -10,13 +10,23 @@ var EVENT_EMITTER2_CONFIG = {
 
 var TYPES = {
   // Flow monitoring events and their params
+  FLOW_BEGIN: 'flow.begin',                        // env
   TASK_BEGIN: 'task.begin',                        // task
   TASK_COMPLETE: 'task.complete',                  // task
+  TASK_ERRORED: 'task.errored',                    // task
+  FLOW_COMPLETE: 'flow.complete',                  // env
+  FLOW_ERRORED: 'flow.errored',                    // env
 
   // Internal Hooks
+  EXEC_FLOW_START: 'exec.flow.start',              // env
   EXEC_INPUT_PREPROCESS: 'exec.input.preprocess',  // parsedInput
-  EXEC_TASKS_PRECREATE: 'exec.tasks.precreate',     // taskEnv
-  EXEC_OUTTASK_CREATE: 'exec.outTask.create'      // outTaskOptions
+  EXEC_TASKS_PRECREATE: 'exec.tasks.precreate',    // env
+  EXEC_OUTTASK_CREATE: 'exec.outTask.create',      // outTaskOptions
+  EXEC_TASK_START: 'exec.task.start',              // task
+  EXEC_TASK_COMPLETE: 'exec.task.complete',        // task
+  EXEC_TASK_ERRORED: 'exec.task.errored',          // task
+  EXEC_FLOW_COMPLETE: 'exec.flow.complete',        // env
+  EXEC_FLOW_ERRORED: 'exec.flow.errored'           // env
 };
 
 /**
@@ -52,18 +62,10 @@ EventManager.prototype.emit = function (event, arg1, arg2, argN) {
   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);
+EventManager.prototype.removeListener = function (event, listener) {
+  if (this.emitter) this.emitter.removeListener.apply(this.emitter, arguments);
 };
 
+
 module.exports = EventManager;
 module.exports.global = EventManager.create(); // create one top level emitter

package/lib/finalcb-first-task.js

@@ -5,23 +5,22 @@ var util = require('util');
 
 var STATUS = require('./status.js');
 var VContext = require('./vcon.js');
+var EventManager = require('./event-manager.js');
 
 var OUTTASK_A_REQ = 'ast.outTask.a should be an array of string param names';
 
 function FinalCbFirstSuccTask(outTaskOptions) {
   var taskDef = outTaskOptions.taskDef;
-  var cbFunc = outTaskOptions.cbFunc;
-  var tasks = outTaskOptions.tasks;
-  var vCon = outTaskOptions.vCon;
-  var execOptions = outTaskOptions.execOptions;
-  var retValue = outTaskOptions.retValue;
-  if (typeof(cbFunc) !== 'function') throw new Error('callback is not a function'); 
+  if (typeof(outTaskOptions.cbFunc) !== 'function') throw new Error('callback is not a function'); 
   var self = this;
-  Object.keys(taskDef).forEach(function (k) { self[k] = taskDef[k]; });
-  this.f = cbFunc;
-  this.tasks = tasks;
-  this.vCon = vCon;
-  this.retValue = retValue;
+  for (var k in taskDef) {
+    if (true) self[k] = taskDef[k];  // if to make jshint happy
+  }
+  this.f = outTaskOptions.cbFunc;
+  this.tasks = outTaskOptions.tasks;
+  this.vCon = outTaskOptions.vCon;
+  this.retValue = outTaskOptions.retValue;
+  this.env = outTaskOptions.env;
 }
 
 function format_error(errmsg, obj) {
@@ -49,11 +48,15 @@ FinalCbFirstSuccTask.prototype.isReady = function () {
 FinalCbFirstSuccTask.prototype.exec = function (err) {
   if (!this.f) return;   //must have already been called
   if (err) {
+    this.env.error = err;
+    this.env.flowEmitter.emit(EventManager.TYPES.EXEC_FLOW_ERRORED, this.env);
     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.env.results = finalArgs;
+    this.env.flowEmitter.emit(EventManager.TYPES.EXEC_FLOW_COMPLETE, this.env);
     this.f.apply(null, finalArgs);
   }
   this.f = null;   // prevent multiple calls

package/lib/finalcb-task.js

@@ -4,23 +4,23 @@ var sprintf = require('sprintf').sprintf;
 var util = require('util');
 
 var STATUS = require('./status.js');
+var EventManager = require('./event-manager.js');
 
 var OUTTASK_A_REQ = 'ast.outTask.a should be an array of string param names';
 
 function FinalCbTask(outTaskOptions) {
   var taskDef = outTaskOptions.taskDef;
-  var cbFunc = outTaskOptions.cbFunc;
-  var tasks = outTaskOptions.tasks;
-  var vCon = outTaskOptions.vCon;
-  var execOptions = outTaskOptions.execOptions;
-  var retValue = outTaskOptions.retValue;
-  if (typeof(cbFunc) !== 'function') throw new Error('callback is not a function'); 
+  if (typeof(outTaskOptions.cbFunc) !== 'function') throw new Error('callback is not a function'); 
   var self = this;
-  Object.keys(taskDef).forEach(function (k) { self[k] = taskDef[k]; });
-  this.f = cbFunc;
-  this.tasks = tasks;
-  this.vCon = vCon;
-  this.retValue = retValue;
+  for (var k in taskDef) {
+    if (true) self[k] = taskDef[k];  // if to make jshint happy
+  }
+  this.f = outTaskOptions.cbFunc;
+  this.tasks = outTaskOptions.tasks;
+  this.vCon = outTaskOptions.vCon;
+  this.retValue = outTaskOptions.retValue;
+  this.execOptions = outTaskOptions.execOptions;
+  this.env = outTaskOptions.env;
 }
 
 function format_error(errmsg, obj) {
@@ -44,11 +44,15 @@ FinalCbTask.prototype.isReady = function () {
 FinalCbTask.prototype.exec = function (err) {
   if (!this.f) return;   //must have already been called
   if (err) {
+    this.env.error = err;
+    this.env.flowEmitter.emit(EventManager.TYPES.EXEC_FLOW_ERRORED, this.env);
     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.env.results = finalArgs;
+    this.env.flowEmitter.emit(EventManager.TYPES.EXEC_FLOW_COMPLETE, this.env);
     this.f.apply(null, finalArgs);
   }
   this.f = null;   // prevent multiple calls

package/lib/log-events.js

@@ -0,0 +1,71 @@
+'use strict';
+
+/**
+   Log events to console.error
+
+   @example
+   var react = require('react');
+   require('react/lib/log-events').logEvent(react);
+  */
+
+var react = require('../lib/track-tasks');  // require('react/lib/track-tasks'); // turn on tracking
+
+var ALL_FLOW_EVENTS = 'flow.*';
+var ALL_TASK_EVENTS = 'task.*';
+
+function flowLog(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);
+  }    
+}
+
+function taskLog(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 === 'task.complete') {
+    var task = obj;
+    console.error('%s: %s \tmsecs:(%s) \n\targs:(%s) \n\tresults:(%s)\n',
+                  this.event, task.name, task.elapsedTime, argsNoCb, task.results);
+  } else {
+    var name = obj.name;
+    var args = obj.args;
+    console.error('%s: %s \n\targs:(%s)\n', this.event, name, argsNoCb);
+  }
+  
+}
+
+/**
+   Log flow and task events for a flowFn or all of react.
+   If called multiple times, remove previous listener (if any) before
+   adding.
+   
+   @example
+   var react = require('react');
+   require('react/lib/log-events').logEvents(flowFn); // pass flowFn or react
+   
+   @param flowFn Flow function or global react object
+  */
+function logEvents(flowFn) {
+  //output events as tasks start and complete
+  flowFn.events.removeListener(ALL_FLOW_EVENTS, flowLog);
+  flowFn.events.on(ALL_FLOW_EVENTS, flowLog);
+  flowFn.events.removeListener(ALL_TASK_EVENTS, taskLog);
+  flowFn.events.on(ALL_TASK_EVENTS, taskLog);
+}
+
+module.exports = react;
+module.exports.logEvents = logEvents;

package/lib/task.js

@@ -163,7 +163,7 @@ function create(taskDef) {
   return new TaskConstructor(taskDef);
 }
 
-function createOutTask(taskDef, cbFunc, tasks, vCon, execOptions) {
+function createOutTask(taskDef, cbFunc, tasks, vCon, execOptions, env) {
   setMissingOutTaskType(taskDef);
   var outTaskOptions = {
     taskDef: taskDef,
@@ -171,6 +171,7 @@ function createOutTask(taskDef, cbFunc, tasks, vCon, execOptions) {
     tasks: tasks,
     vCon: vCon,
     execOptions: execOptions,
+    env: env,
     TaskConstructor: OUT_TASK_TYPES[taskDef.type]
   };
   EventManager.global.emit(EventManager.TYPES.EXEC_OUTTASK_CREATE, outTaskOptions); // hook
@@ -181,6 +182,9 @@ function createOutTask(taskDef, cbFunc, tasks, vCon, execOptions) {
 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
   };
@@ -202,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);
   });
@@ -210,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);
 }