react 0.1.2 → 0.2.3

package/.npmignore

@@ -2,4 +2,5 @@ node_modules
 npm-debug.log
 ./npmrc
 todo.md
-notes.md
+notes.md
+oldExamples

package/README.md

@@ -25,13 +25,13 @@ It takes inspiration from several projects including:
 
 ## Goals
 
+ - Minimize boilerplate code needed for working with asynchronous functions
+ - Minimize the need to customize your code simply to use async flow control. The use of a flow control module ideally should not affect the way you write your code, it should only help take over some of the burden.
  - Improved error and exception handling
  - Provide useful stack traces and context information for easier debugging
- - Minimize boilerplate code needed for working with asynchronous functions
  - Make code more readable and easier to understand which should translate to less defects
  - Provide the right level of abstraction to make it easier to refactor code, without being too magical
  - Allow the mixing of pure functions, method calls, and callback style functions in the flow
- - Minimize the need to customize your code simply to use async flow control. The use of a flow control module ideally should not affect the way you write your code, it should only help take over some of the burden.
 
 ## Supports
 
@@ -61,9 +61,9 @@ To reduce the boilerplate code needed and improve error handling, React automati
 
 ## Design
 
- - Parse and validate ad module load time
+ - Parse and validate DSL rules at module load time
  - Validate the flow AST at module load time - determine if dependencies can all be met as defined
- - Execute the flow AST by calling the function with params
+ - Execute the flow AST by calling the function with arguments
 
 ## Installing
 
@@ -75,8 +75,8 @@ Pull from github - http://github.com/jeffbski/react
 
 ## Examples
 
- 1. [Direct AST](#directAST)
- 2. [Using Function Str DSL](#fstr)
+ 1. [Default DSL](#defaultDSL)
+ 2. [Direct AST](#directAST)
  3. [Using pseudocode DSL](#pcode)
  4. [Using jquery-like chaining DSL](#chain)
 
@@ -85,6 +85,44 @@ These live in the examples folder so they are ready to run.
 Also see test/module-use.test.js for more examples as well
 as the specific tests for the DSL you want to use.
 
+<a name="defaultDSL"/>
+### Example using default DSL
+
+```javascript
+// in your foo module
+var react = require('react');
+
+// some normal async and sync functions
+function loadUser(uid, cb){ }
+function loadFile(filename, cb){ }
+function markdown(filedata) { }
+function writeOutput(html, user, cb){  }
+function loadEmailTemplate(cb) { }
+function customizeEmail(user, emailHtml, cb) { }
+function deliverEmail(custEmailHtml, cb) { }
+
+// define fn, glue together with react, it will parallelize
+// starts with name and in/out params, then the tasks
+var loadAndSend = react('loadAndSend', 'uid, filename, cb -> err, user',
+  loadUser, 'uid, cb -> err, user',
+  loadFile, 'filename, cb -> err, filemd',
+  markdown, 'filemd -> html',  // no cb, implies sync fn
+  writeOutput, 'html, user, cb -> err, htmlBytesWritten',
+  loadEmailTemplate, 'cb -> err, emailmd',
+  markdown, 'emailmd -> emailHtml',  // no cb, implies sync fn
+  customizeEmail, 'user, emailHtml, cb -> err, custEHtml',
+  deliverEmail, 'custEHtml, cb -> err, custBytesWritten'
+);
+exports.loadAndSend = loadAndSend; // is a normal fn created by react
+
+// in a different module far far away, use this as any other node function
+var foo = require('foo');
+foo.loadAndSend(100, 'bar.md', function (err, user) {
+  // tasks were parallelized based on their depedencies
+}
+```
+
+
 <a name="directAST"/>
 ### Example directly using AST
 
@@ -204,6 +242,7 @@ fn(2, 3, function (err, m, s) {
 
 ## Status
 
+ - 2012-01-10 - Create default DSL for react(), create error for missing variables, list remaining tasks when flow won't complete
  - 2011-12-21 - Refactor from ground up with tests, changes to the interfaces
  - 2011-10-26 - React is in active development and interface may change frequently in these early stages. Current code is functional but does not perform validation yet.  Additional interfaces are planned to make it easy to define flows in a variety of ways. Documentation and examples forthcoming.
 
@@ -214,12 +253,13 @@ ok ast.test.js .................... 10/10
 ok cb-task.test.js ................ 31/31
 ok chain.test.js .................. 56/56
 ok core.test.js ................... 98/98
+ok dsl.test.js .................... 58/58
 ok event-manager.test.js .......... 13/13
 ok exec-options.test.js ............. 3/3
 ok finalcb-task.test.js ............. 5/5
 ok fstr.test.js ................... 64/64
 ok input-parser.test.js ........... 15/15
-ok module-use.test.js ............. 55/55
+ok module-use.test.js ............. 64/64
 ok pcode.test.js .................. 65/65
 ok ret-task.test.js ............... 31/31
 ok task.test.js ..................... 1/1
@@ -227,7 +267,7 @@ ok validate-cb-task.test.js ......... 6/6
 ok validate-ret-task.test.js ........ 7/7
 ok validate.test.js ............... 26/26
 ok vcon.test.js ................... 42/42
-total ........................... 545/545
+total ........................... 613/613
 
 ok
 ```

package/examples/default-events1.js

@@ -0,0 +1,52 @@
+'use strict';
+/*jshint white: false */
+
+var react = require('../'); // require('react');
+
+//output events as tasks start and complete
+react.events.on('*', 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);
+  }
+});
+                
+
+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  -> err, 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/default1.js

@@ -0,0 +1,41 @@
+'use strict';
+/*jshint white: false */
+
+var react = require('../'); // require('react');
+
+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);
+    console.error(err.stack);
+    return;
+  }
+  console.log('final result: %s, user: %s, written:%s', html, user, bytesWritten);
+}
+
+// define fn, glue together with react, it will parallelize
+// starts with name and in/out params, then the tasks
+var loadAndSave = react('loadAndSave', 'filename, uid, outDir, cb -> err, html, user, bytes',  
+  loadUser,         'uid, cb          -> err, user',     // calling async loadUser with uid, cb called with err and user
+  loadFile,         'filename, cb     -> err, filedata',
+  markdown,         'filedata         -> html',    // using a sync function
+  prepareDirectory, 'outDir, cb   -> err, dircreated',
+  writeOutput,      'html, user, cb   -> err, bytes', { after: prepareDirectory },  // only after prepareDirectory done
+  loadEmailTemplate, 'cb              -> err, emailmd',
+  markdown,         'emailmd          -> emailHtml',   // using a sync function
+  customizeEmail,   'user, emailHtml  -> custEmailHtml',  // sync function
+  deliverEmail,     'custEmailHtml, cb    -> err, deliveredEmail', { after: writeOutput }  // only after writeOutput is done
+);
+
+//in another module you can use this as any other exported fn
+loadAndSave('file.md', 100, '/tmp/foo', useHtml);  // executing the flow
+
+

package/lib/core.js

@@ -45,6 +45,7 @@ function reactFactory() {
   flowEmitter.parent = reactEmitter;
 
   var ast = {
+    name: undefined,
     inParams: [],
     tasks: [],
     outTask: {},

package/lib/dsl.js

@@ -0,0 +1,122 @@
+'use strict';
+/*jshint regexp: false */
+
+var sprintf = require('sprintf').sprintf;
+var core = require('./core.js');
+var parse = require('./parse.js');
+var tutil = require('./task.js');
+
+var INOUT_PARAMS_NO_MATCH = 'params in wrong format, wanted "foo, bar cb -> err, baz" - found: %s';
+var EXTRA_TASKARG = 'extra unmatched task arg: %s';
+
+var CB_NAMES_RE = /^cb|callback$/i;  //cb, Cb, CB, callback, Callback
+var ERR_NAMES_RE = /^err$/i; // err, ERR, Err, ...
+
+function filterOutTrailingCbParam(args) { // if has trailing cb | callback param, filter it out
+  if (args.length && args[args.length - 1].match(CB_NAMES_RE)) args.pop();
+  return args;
+}
+
+function filterOutLeadingErrParam(args) { // if leading err param, filter it out
+  if (args.length && args[0].match(ERR_NAMES_RE)) args.shift();
+  return args;
+}
+
+var inOutDefParse = {
+  regex: /^([^\-]*)(->\s*(.*))?$/i,
+  fn: function (m) {
+    var inParams = parse.splitTrimFilterArgs(m[1]);
+    var lastParam = inParams[inParams.length - 1];
+    var type = (lastParam && CB_NAMES_RE.test(lastParam)) ? 'cb' : 'ret';
+    var outParams = parse.splitTrimFilterArgs(m[3]);
+    return {
+      type: type,
+      inDef: filterOutTrailingCbParam(inParams),
+      outDef: filterOutLeadingErrParam(outParams)
+    };
+  }
+};
+
+function parseInOutParams(str) {
+  var objDef = parse.parseStr(str, [inOutDefParse], INOUT_PARAMS_NO_MATCH);
+  objDef.inDef = filterOutTrailingCbParam(objDef.inDef);
+  return objDef;
+}
+
+function parseTasks(arr) {
+  var tasks = [];
+  var fn, obj, result;
+  while (arr.length >= 2) {
+    obj = {};
+    fn = arr.shift();
+    result = parseInOutParams(arr.shift());
+    if (typeof(arr[0]) === 'object') obj = arr.shift(); // has options, use as obj
+    obj.f = fn;
+    obj.a = result.inDef;
+    var type = result.type;
+    obj.out = result.outDef;
+    obj.type = type;
+    tasks.push(obj);
+  }
+  if (arr.length) throw new Error(sprintf(EXTRA_TASKARG, arr[0]));
+  return tasks;
+}
+
+/**
+   Parse the variable arguments into in/out params, options, tasks
+  */
+function parseVargs(vargs) {
+  var inOutParamStr = vargs.shift() || '';
+  // if next arg is object, shift it off as options
+  var options = (vargs.length && typeof(vargs[0]) === 'object') ? vargs.shift() : { };
+  var taskDefArr = vargs; // rest are for the tasks
+  var defObj = {  
+    inOutParamStr: inOutParamStr,
+    taskDefArr: taskDefArr,
+    options: options
+  };
+  return defObj;
+}
+
+
+function dslDefine(name, arg1, arg2, argN) {
+  var reactFn = core();
+  var defObj = parseVargs(Array.prototype.slice.call(arguments, 1)); // name, already used 
+  var inOutDef = parseInOutParams(defObj.inOutParamStr);
+  var ast = {
+    name: name,
+    inParams: inOutDef.inDef,
+    tasks: parseTasks(defObj.taskDefArr),
+    outTask: { a: inOutDef.outDef }
+  };
+  if (defObj.options) Object.keys(defObj.options).forEach(function (k) { ast[k] = defObj.options[k]; });
+  var errors = reactFn.setAndValidateAST(ast);
+  if (errors.length) {
+    var errorStr = errors.join('\n');
+    throw new Error(errorStr);
+  }
+  return reactFn;
+}
+
+function selectFirst(name, arg1, arg2, argN) {
+  var reactFn = core();
+  var defObj = parseVargs(Array.prototype.slice.call(arguments, 1)); // name, already used 
+  var inOutDef = parseInOutParams(defObj.inOutParamStr);  
+  var tasks = tutil.serializeTasks(parseTasks(defObj.taskDefArr));
+  var ast = {
+    name: name,
+    inParams: inOutDef.inDef,
+    tasks: tasks,
+    outTask: { type: 'finalcbFirst', a: inOutDef.outDef },
+  };
+  if (defObj.options) Object.keys(defObj.options).forEach(function (k) { ast[k] = defObj.options[k]; });  
+  var errors = reactFn.setAndValidateAST(ast);
+  if (errors.length) {
+    var errorStr = errors.join('\n');
+    throw new Error(errorStr);
+  }
+  return reactFn;
+}
+
+module.exports = dslDefine;
+module.exports.selectFirst = selectFirst;

package/lib/error.js

@@ -9,19 +9,29 @@ function ensureStackTraceLimitSet(stackTraceLimit) {
 }
 
 function fName(fn) {
-  return (typeof(fn) === 'string') ? fn : fn.name;
+  if (!fn) return 'undefined';
+  return (fn && fn.name) ? fn.name : fn;
 }
 
 function formatErrorMeta(err) {
   if (!err.meta) return;
   var vcon = err.meta.vcon;
   var task = err.meta.task;
-  return '\n\n' +
-      'Error occurs in Task function: ' + fName(task.f) + '(' + task.a.join(',') + ')\n\n' + 
-      'Variable Context: \n' +
-      util.inspect(vcon) + '\n\n' +
-      'Task Source:\n\n' +
-      task.f.toString() + '\n\n'; //TODO need to pretty print function, gets collapsed
+  var errString = '\n\n';
+  if (task && task.f && task.a) {
+    errString += ('Error occurs in Task function: ' + fName(task.f) + '(' + task.a.join(',') + ')\n\n');
+  }
+  if (vcon) {
+    errString += 'Variable Context: \n';
+    errString += util.inspect(vcon);
+    errString +=  '\n\n';
+  }
+  if (task && task.f) {
+    errString += 'Task Source:\n\n';
+    errString += task.f.toString(); //TODO need to pretty print function, gets collapsed
+    errString += '\n\n';
+  }
+  return errString;    
 }
 
 function augmentError(err, meta) {

package/lib/parse.js

@@ -3,6 +3,7 @@
 var sprintf = require('sprintf').sprintf;
 
 function splitTrimFilterArgs(commaSepArgs) { //parse 'one, two' into ['one', 'two']
+  if (!commaSepArgs) return [];
   return commaSepArgs.split(',')            //split on commas
     .map(function (s) { return s.trim(); }) //trim
     .filter(function (s) { return (s); });  //filter out empty strings

package/lib/task.js

@@ -25,7 +25,7 @@ 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 NO_TASKS_RUNNING_WONT_COMPLETE = 'no tasks running, flow will not complete, remaining tasks: %s';
 var TASK_TYPE_SHOULD_MATCH = 'task.type should match one of ' +
   Object.keys(TASK_TYPES).join(', ');
 
@@ -201,7 +201,12 @@ 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));
+  if (!tasksRunning.length) {
+    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));
+  }
 }
 
 function findReadyAndExec(vCon, tasks, tasksByName, handleError, contExec) {

package/lib/validate.js

@@ -11,14 +11,19 @@ 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 MISSING_INPUTS = 'missing or mispelled variable referenced in flow definition: %s';
 
 var validateInParams, validateTasks, validateOutTask, validateTaskNamesUnique;
-var validateLocals, validateOuputsUnique;
+var validateLocals, validateOuputsUnique, validateNoMissingNames;
 
 function format_error(errmsg, obj) {
   return sprintf('%s - %s', errmsg, util.inspect(obj));
 }
 
+function isProp(str) { // true if is a property name (contains a dot)
+  return (str.indexOf('.') !== -1);
+}
+
 /**
    validate the AST return Errors
    @example
@@ -37,6 +42,7 @@ function validate(ast) {
   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));
+    errors = errors.concat(validateNoMissingNames(ast));
   }
   return errors;
 }
@@ -99,4 +105,46 @@ function validateOuputsUnique(taskDefs) {
   return errors;
 }
 
+/**
+   validate there are no missing or mispelled param names in any task inputs
+   or the final task output
+
+   @return array of errors, or empty array if none
+  */
+function validateNoMissingNames(ast) {
+  var errors = [];
+  var names = {};
+  if (ast.locals) {
+    names = Object.keys(ast.locals).reduce(function (accum, k) { // start with locals
+      accum[k] = true;
+      return accum;
+    }, names);
+  }
+  ast.inParams.reduce(function (accum, p) {  // add input params
+    accum[p] = true;
+    return accum;
+  }, names);
+  ast.tasks.reduce(function (accum, t) { // add task outputs
+    return t.out.reduce(function (innerAccum, p) {
+      innerAccum[p] = true;
+      return innerAccum;
+    }, accum);
+  }, names);
+
+  // now we have all possible provided vars, check task inputs are accounted for
+  ast.tasks.reduce(function (accum, t) {  // for all tasks
+    return t.a.reduce(function (innerAccum, p) { // for all in params, except property
+      if (!isProp(p) && !names[p]) innerAccum.push(sprintf(MISSING_INPUTS, p)); // add error if missing
+      return innerAccum;
+    }, accum);
+  }, errors);
+
+  // now check the final task outputs
+  ast.outTask.a.reduce(function (accum, p) { // for final task out params
+    if (!isProp(p) && !names[p]) accum.push(sprintf(MISSING_INPUTS, p)); // add error if missing
+    return accum;
+  }, errors);
+  return errors;
+}
+
 module.exports = validate;

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.1.2",
+  "version": "0.2.3",
   "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" },

package/react.js

@@ -2,11 +2,11 @@
 
 var core = require('./lib/core.js');
 
-module.exports = core;
-module.exports.options = core.options;
-module.exports.events = core.events;   // top level emitter
+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
 
-// interfaces
+// additional interfaces
 module.exports.fstrDefine = require('./lib/fstr.js');
 module.exports.pcodeDefine = require('./lib/pcode.js');
 module.exports.chainDefine = require('./lib/chain.js');

package/test/chain.test.js

@@ -63,10 +63,11 @@ test('in triple first param -> inParams["foo", "bar", "baz"]', function (t) {
 
 test('single task, single out params', function (t) {
   var fn = chainDefine()
+    .in('a', 'b')
     .out('c')
     .async(falpha).in('a', 'b').out('c')
     .end();
-  t.deepEqual(fn.ast.inParams, []);
+  t.deepEqual(fn.ast.inParams, ['a', 'b']);
   t.deepEqual(fn.ast.tasks, [
     { f: falpha, type: 'cb', a: ['a', 'b'], out: ['c'], name: 'falpha' }
   ]);
@@ -77,11 +78,11 @@ test('single task, single out params', function (t) {
 test('single task, err and out params', function (t) {
   var fn = chainDefine()
     .out('err', 'c')
-    .async(falpha).in('a', 'b').out('err', 'c')
+    .async(falpha).in().out('err', 'c')
     .end();
   t.deepEqual(fn.ast.inParams, []);
   t.deepEqual(fn.ast.tasks, [
-    { f: falpha, type: 'cb', a: ['a', 'b'], out: ['c'], name: 'falpha' }
+    { f: falpha, type: 'cb', a: [], out: ['c'], name: 'falpha' }
   ]);
   t.deepEqual(fn.ast.outTask, { a: ['c'], type: 'finalcb' });
   t.end();  
@@ -90,11 +91,11 @@ test('single task, err and out params', function (t) {
 test('single task, ERR and out params', function (t) {
   var fn = chainDefine()
     .out('ERR', 'c')
-    .async(falpha).in('a', 'b').out('ERR', 'c')
+    .async(falpha).in().out('ERR', 'c')
     .end();
   t.deepEqual(fn.ast.inParams, []);
   t.deepEqual(fn.ast.tasks, [
-    { f: falpha, type: 'cb', a: ['a', 'b'], out: ['c'], name: 'falpha' }
+    { f: falpha, type: 'cb', a: [], out: ['c'], name: 'falpha' }
   ]);
   t.deepEqual(fn.ast.outTask, { a: ['c'], type: 'finalcb' });
   t.end();  

package/test/core.test.js

@@ -198,14 +198,15 @@ test('error when cant complete', function (t) {
     inParams: ['a', 'b', 'c'],
     tasks: [    
       { f: multiply, a: ['a', 'b'], out: ['c.mult'] },
-      { f: fnRetsSum, a: ['c.bad', 'b'], out: ['c.sum'], type: 'ret' }
+      { f: fnRetsSum, a: ['c.bad', 'b'], out: ['c.sum'], type: 'ret' },
+      { f: add, a: ['c.sum', 'a'], out: ['d']}
     ],
-    outTask: { a: ['c.mult', 'c.sum', 'c'] }
+    outTask: { a: ['c.mult', 'c.sum', 'd'] }
   });
   t.deepEqual(errors, [], 'no validation errors');
 
-  fn(2, 3, { foo: 1 }, function (err, cmult, csum, c) {
-    t.equal(err.message, 'no tasks running, flow will not complete');
+  fn(2, 3, { foo: 1 }, function (err, cmult, csum, d) {
+    t.equal(err.message, 'no tasks running, flow will not complete, remaining tasks: fnRetsSum, add');
     t.end();
   });
 });

package/test/dsl.test.js

@@ -0,0 +1,265 @@
+'use strict';
+
+var test = require('tap').test;
+var sprintf = require('sprintf').sprintf;
+
+var react = require('../'); // require('react');
+
+function falpha() { }
+function fbeta() { }
+
+test('module exports is a fn with properties', function (t) {
+  t.type(react, 'function', 'has define by DSL method'); //
+  t.type(react.selectFirst, 'function', 'has selectFirst define method');
+  t.end();
+});
+
+test('no arguments -> empty name, inParams, tasks, outTask', function (t) {
+  var r = react();
+  t.equal(r.ast.name, undefined);
+  t.deepEqual(r.ast.inParams, []);
+  t.deepEqual(r.ast.tasks, []);
+  t.deepEqual(r.ast.outTask, { a: [], type: 'finalcb' });
+  t.end();
+});
+
+
+test('empty first string -> empty name, inParams, tasks, outTask', function (t) {
+  var r = react('');
+  t.equal(r.ast.name, '');
+  t.deepEqual(r.ast.inParams, []);
+  t.deepEqual(r.ast.tasks, []);
+  t.deepEqual(r.ast.outTask, { a: [], type: 'finalcb' });
+  t.end();
+});
+
+
+test('single first string -> name, inParams["foo"], empty tasks, outTask', function (t) {
+  var r = react('foo');
+  t.equal(r.ast.name, 'foo');
+  t.deepEqual(r.ast.inParams, []);
+  t.deepEqual(r.ast.tasks, []);
+  t.deepEqual(r.ast.outTask, { a: [], type: 'finalcb' });
+  t.end();
+});
+
+test('triple first string -> inParams["foo", "bar", "baz"], empty tasks, outTask',
+     function (t) {
+  var r = react('myName', ' foo,   bar,baz  ');
+  t.equal(r.ast.name, 'myName');
+  t.deepEqual(r.ast.inParams, ['foo', 'bar', 'baz']);
+  t.deepEqual(r.ast.tasks, []);
+  t.deepEqual(r.ast.outTask, { a: [], type: 'finalcb' });
+  t.end();
+});
+
+test('single task, single out params', function (t) {
+  var r = react('myName', 'cb -> err, c',
+    falpha, 'cb -> err, c'
+  );
+  t.deepEqual(r.ast.inParams, []);
+  t.deepEqual(r.ast.tasks, [
+    { f: falpha, a: [], out: ['c'], type: 'cb', name: 'falpha'}
+  ]);
+  t.deepEqual(r.ast.outTask, { a: ['c'], type: 'finalcb' });
+  t.end();  
+});
+
+test('single task, err and out params', function (t) {
+  var r = react('myName', 'cb -> err, c',
+    falpha, 'cb -> err, c'
+  );
+  t.deepEqual(r.ast.inParams, []);
+  t.deepEqual(r.ast.tasks, [
+    { f: falpha, a: [], out: ['c'], type: 'cb', name: 'falpha'}
+  ]);
+  t.deepEqual(r.ast.outTask, { a: ['c'], type: 'finalcb' });
+  t.end();  
+});
+
+test('single task, ERR and out params', function (t) {
+  var r = react('myName', 'cb -> ERR, c', 
+    falpha, 'cb -> ERR, c'
+  );
+  t.deepEqual(r.ast.inParams, []);
+  t.deepEqual(r.ast.tasks, [
+    { f: falpha, a: [], out: ['c'], type: 'cb', name: 'falpha'}
+  ]);
+  t.deepEqual(r.ast.outTask, { a: ['c'], type: 'finalcb' });
+  t.end();  
+});
+
+test('cb used in defs is simply ignored', function (t) {
+  var r = react('myName', 'a, b, cb -> err, c', 
+    falpha, 'a, b, cb -> err, c'
+  );
+  t.deepEqual(r.ast.inParams, ['a', 'b']);
+  t.deepEqual(r.ast.tasks, [
+    { f: falpha, a: ['a', 'b'], out: ['c'], type: 'cb', name: 'falpha'}
+  ]);
+  t.deepEqual(r.ast.outTask, { a: ['c'], type: 'finalcb' });
+  t.end();  
+});
+
+test('callback used in defs is simply ignored', function (t) {
+  var r = react('myName', 'a, b, callback -> err, c',
+    falpha, 'a, b, callback -> err, c'
+  );
+  t.deepEqual(r.ast.inParams, ['a', 'b']);
+  t.deepEqual(r.ast.tasks, [
+    { f: falpha, a: ['a', 'b'], out: ['c'], type: 'cb', name: 'falpha'}
+  ]);
+  t.deepEqual(r.ast.outTask, { a: ['c'], type: 'finalcb' });
+  t.end();  
+});
+
+test('two inputs, two tasks, two out params', function (t) {
+  var r = react('myName', 'a, b, cb -> err, c, d',
+    falpha, 'a, b, cb -> err, c',
+    fbeta,  'a, b, cb -> err, d, e'
+  );
+  t.deepEqual(r.ast.inParams, ['a', 'b']);
+  t.deepEqual(r.ast.tasks, [
+    { f: falpha, a: ['a', 'b'], out: ['c'], type: 'cb', name: 'falpha'},
+    { f: fbeta,  a: ['a', 'b'], out: ['d', 'e'], type: 'cb', name: 'fbeta'}
+  ]);
+  t.deepEqual(r.ast.outTask, { a: ['c', 'd'], type: 'finalcb' });
+  t.end();  
+});
+
+test('two inputs, two tasks, two out params, options', function (t) {
+  var r = react('myName', 'a, b, cb -> err, c, d',
+    { otherOptFoo: 'foo'},  // main flow options
+    falpha, 'a, b, cb -> err, c',
+    fbeta,  'a, b, cb -> err, d, e'
+  );
+  t.deepEqual(r.ast.inParams, ['a', 'b']);
+  t.deepEqual(r.ast.tasks, [
+    { f: falpha, a: ['a', 'b'], out: ['c'], type: 'cb', name: 'falpha'},
+    { f: fbeta,  a: ['a', 'b'], out: ['d', 'e'], type: 'cb', name: 'fbeta'}
+  ]);
+  t.deepEqual(r.ast.outTask, { a: ['c', 'd'], type: 'finalcb' });
+  t.equal(r.ast.name, 'myName', 'name should match');
+  t.equal(r.ast.otherOptFoo, 'foo', 'other options should pass through');
+  t.end();  
+});
+
+test('two inputs, two mixed tasks, two out params', function (t) {
+  var r = react('myName', 'a, b, cb -> err, c, d',
+    falpha, 'a, b, cb -> err, c',
+    fbeta,  'a, b -> d'
+  );
+  t.deepEqual(r.ast.inParams, ['a', 'b']);
+  t.deepEqual(r.ast.tasks, [
+    { f: falpha, a: ['a', 'b'], out: ['c'], type: 'cb', name: 'falpha'},
+    { f: fbeta,  a: ['a', 'b'], out: ['d'], type: 'ret', name: 'fbeta'}
+  ]);
+  t.deepEqual(r.ast.outTask, { a: ['c', 'd'], type: 'finalcb' });
+  t.end();  
+});
+
+
+test('two inputs, two mixed tasks, two out params, opts', function (t) {
+  var r = react('myName', 'a, b, cb -> err, c, d', 
+    falpha, 'a, cb -> err, c', { after: fbeta },
+    fbeta,  'a, b -> d'
+  );
+  t.deepEqual(r.ast.inParams, ['a', 'b']);
+  t.deepEqual(r.ast.tasks, [
+    { after: ['fbeta'], f: falpha, a: ['a'], out: ['c'], type: 'cb', name: 'falpha'},
+    { f: fbeta,  a: ['a', 'b'], out: ['d'], type: 'ret', name: 'fbeta'}
+  ]);
+  t.deepEqual(r.ast.outTask, { a: ['c', 'd'], type: 'finalcb' });
+  t.end();  
+});
+
+
+// Object use
+test('object prop task params', function (t) {
+  var r = react('myName', 'a, b, cb -> err, c, e', 
+    falpha, 'a, b.cat, cb -> err, c',
+    fbeta,  'c.dog, b -> d',
+    'd.egg', 'c, cb -> err, e'
+  );
+  t.deepEqual(r.ast.inParams, ['a', 'b']);
+  t.deepEqual(r.ast.tasks, [
+    { f: falpha, a: ['a', 'b.cat'], out: ['c'], type: 'cb', name: 'falpha'},
+    { f: fbeta,  a: ['c.dog', 'b'], out: ['d'], type: 'ret', name: 'fbeta'},
+    { f: 'd.egg', a: ['c'], out: ['e'], type: 'cb', name: 'd.egg'}
+  ]);
+  t.deepEqual(r.ast.outTask, { a: ['c', 'e'], type: 'finalcb' });
+  t.end();  
+});
+
+test('extra arg throws error', function (t) {
+  var fn = function () {
+    var r = react('myName', 'a, b, cb -> err, c, d', 
+      falpha, 'a -> err, c', { after: fbeta },
+      fbeta,  'a, b -> returns d',
+      'extraBadArg'
+    );
+  };
+  t.throws(fn, new Error('extra unmatched task arg: extraBadArg'));
+  t.end();  
+});
+
+test('not enough args throws error', function (t) {
+  var fn = function () {
+    var r = react('myName', 'a, b, cb -> c, d', 
+      falpha, 'a -> err, c', { after: fbeta },
+      fbeta
+    );
+  };
+  t.throws(fn, new Error(sprintf('extra unmatched task arg: %s', fbeta)));
+  t.end();  
+});
+
+test('long example', function (t) {
+  t.plan(4);
+  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); }
+  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',
+    deliverEmail,     'custEmailHtml, cb -> err, deliveredEmail', { after: writeOutput }  // only after writeOutput is done
+  );
+  loadAndSave('file.md', 100, '/tmp/foo', function (err, html, user, bytesWritten) {  // executing the flow
+    t.equal(err, null);
+    t.equal(html, 'htmlFiledatafile.md');
+    t.equal(user, 'User100');
+    t.equal(bytesWritten, 'htmlFiledatafile.md_bytesWritten');
+    t.end();
+  });
+});
+
+// selectFirst 
+
+test('selectFirst', function (t) {
+  var r = react.selectFirst('myName', 'a, b, cb -> c',
+    { otherOptFoo: 'foo'},  // main options                            
+    falpha, 'a, b, cb -> err, c',
+    fbeta,  'a, b -> c'
+  );
+  t.equal(r.ast.name, 'myName');
+  t.deepEqual(r.ast.inParams, ['a', 'b']);
+  t.deepEqual(r.ast.tasks, [
+    { f: falpha, a: ['a', 'b'], out: ['c'], type: 'cb', name: 'falpha'},
+    { f: fbeta,  a: ['a', 'b'], out: ['c'], type: 'ret', name: 'fbeta', after: ['falpha']}
+  ]);
+  t.deepEqual(r.ast.outTask, { type: 'finalcbFirst', a: ['c'] });
+  t.equal(r.ast.name, 'myName', 'name should match if supplied');
+  t.equal(r.ast.otherOptFoo, 'foo', 'other options should pass through');
+  t.end();  
+});

package/test/fstr.test.js

@@ -48,10 +48,10 @@ test('triple first string -> inParams["foo", "bar", "baz"], empty tasks, outTask
 });
 
 test('single task, single out params', function (t) {
-  var r = fstrDefine('', [
+  var r = fstrDefine('a, b', [
     falpha, 'a, b -> err, c'
   ], 'c');
-  t.deepEqual(r.ast.inParams, []);
+  t.deepEqual(r.ast.inParams, ['a', 'b']);
   t.deepEqual(r.ast.tasks, [
     { f: falpha, a: ['a', 'b'], out: ['c'], type: 'cb', name: 'falpha'}
   ]);
@@ -60,10 +60,10 @@ test('single task, single out params', function (t) {
 });
 
 test('single task, err and out params', function (t) {
-  var r = fstrDefine('', [
+  var r = fstrDefine('a, b', [
     falpha, 'a, b -> err, c'
   ], 'err, c');
-  t.deepEqual(r.ast.inParams, []);
+  t.deepEqual(r.ast.inParams, ['a', 'b']);
   t.deepEqual(r.ast.tasks, [
     { f: falpha, a: ['a', 'b'], out: ['c'], type: 'cb', name: 'falpha'}
   ]);
@@ -72,10 +72,10 @@ test('single task, err and out params', function (t) {
 });
 
 test('single task, ERR and out params', function (t) {
-  var r = fstrDefine('', [
+  var r = fstrDefine('a, b', [
     falpha, 'a, b -> ERR, c'
   ], 'ERR, c');
-  t.deepEqual(r.ast.inParams, []);
+  t.deepEqual(r.ast.inParams, ['a', 'b']);
   t.deepEqual(r.ast.tasks, [
     { f: falpha, a: ['a', 'b'], out: ['c'], type: 'cb', name: 'falpha'}
   ]);

package/test/module-use.test.js

@@ -9,13 +9,16 @@ var react = require('../react');
   @example
   var react = require('react');
   react.options.an_option = 'something';
-  
-  var loadAndSave = react.fstrDefine('one, two, cb -> err, result1, result2',
-    foo, 'one      -> err, cat',
-    bar, 'two, cat -> err, dog',
-    baz, 'dog      -> err, result1',
-    bum, 'dog      -> err, result2');
-  
+
+  // define function
+  var loadAndSave = react('myName', 'one, two, cb -> err, result1, result2',
+    foo, 'one, cb      -> err, cat',
+    bar, 'two, cat, cb -> err, dog',
+    baz, 'dog, cb      -> err, result1',
+    bum, 'dog, cb      -> err, result2');
+
+  // OR using AST
+    
   var loadAndSave = react();
   loadAndSave.setAndValidateAST({
     inParams: ['one', 'two'],
@@ -26,11 +29,11 @@ var react = require('../react');
   //if you want to listen to task completion events
   loadAndSave.events.on('task.complete', function (taskObj) { });
 
-  loadAndSave(1,2,cb);
+  loadAndSave(1,2,cb); // execute like any other function
  */
 
 test('module exports an function object with properties', function (t) {
-  t.type(react, 'function', 'is a core constructor function');
+  t.type(react, 'function', 'is a core constructor and default dsl function');
   t.type(react.options, 'object', 'has property for global react options');
   t.type(react.fstrDefine, 'function', 'has fn property for using fstr dsl');
   t.type(react.pcodeDefine, 'function', 'has fn property for using pcode dsl');
@@ -47,15 +50,7 @@ test('calling react constructor function creates new function with ast', functio
   t.type(r.ast, 'object', 'is object for inspecting AST');
   t.deepEqual(r.ast.inParams, [],              'ast.inParams should return empty array');
   t.deepEqual(r.ast.tasks, [],                 'ast.tasks() should return empty array');
-  t.deepEqual(r.ast.outTask, {},                   'should return empty object');
-  t.end();
-});
-
-test('deprecated react API should throw to help debugging', function (t) {
-  function badUse() { 
-    var r = react('filename, uid, outDirname, cb'); //this should throw
-  }
-  t.throws(badUse, new Error('react() takes no args, check API'));
+  t.deepEqual(r.ast.outTask, { a: [], type: 'finalcb' });
   t.end();
 });
 
@@ -78,6 +73,57 @@ test('setAndValidateAST sets the ast and validates returning errors', function (
   t.end();
 });
 
+test('use react() default DSL from module', function (t) {
+  t.plan(3);
+  function multiply(a, b, cb) { cb(null, a * b); }
+  function add(a, b, cb) { cb(null, a + b); }
+  var fn = react('multiplyAdd', 'a, b, cb -> err, m, s',
+    multiply, 'a, b, cb -> err, m',
+    add, 'm, a, cb -> err, s'
+  );
+  
+  fn(2, 3, function (err, m, s) {
+    t.deepEqual(err, null, 'should not be any error');
+    t.equal(m, 6);
+    t.equal(s, 8);
+    t.end();
+  });
+});
+
+test('use react.selectFirst() default DSL with events', function (t) {
+  t.plan(7);
+  function noSuccess(a, b, cb) {
+    setTimeout(function () { cb(null); }, 100); // returns undefined result
+  }
+  function noSuccessNull(a, b, cb) { cb(null, null); } // returns null result
+  function add(a, b, cb) { cb(null, a + b); }
+
+  var events = [];
+  function accumEvents(task) {
+    events.push(task);
+  }
+  
+  var fn = react.selectFirst('mySelectFirst', 'a, b, cb -> err, c',
+    noSuccess, 'a, b, cb -> err, c',
+    noSuccessNull, 'a, b, cb -> err, c',
+    add, 'a, b, cb -> err, c',
+    noSuccess, 'a, b, cb -> err, c'                             
+  );
+
+  fn.events.on('task.complete', accumEvents);
+  
+  fn(2, 3, function (err, c) {
+    t.deepEqual(err, null, 'should not be any error');
+    t.equal(c, 5);
+    t.equal(events.length, 3, 'should have seen two task compl events');
+    t.equal(events[0].name, 'noSuccess', 'name matches');
+    t.equal(events[1].name, 'noSuccessNull', 'name matches');
+    t.equal(events[2].name, 'add', 'name matches');
+    t.deepEqual(events[2].results, [5], 'results match');
+    t.end();
+  });
+});
+
 
 test('use pcodeDefine from module', function (t) {
   t.plan(3);

package/test/pcode.test.js

@@ -50,11 +50,11 @@ test('triple first string -> inParams["foo", "bar", "baz"], empty tasks, outTask
 
 test('single task, single out params', function (t) {
   var locals = { falpha: falpha };
-  var r = pcode('', [
+  var r = pcode('a, b', [
     'c := falpha(a, b)',
     'cb(err, c)'
   ], locals);
-  t.deepEqual(r.ast.inParams, []);
+  t.deepEqual(r.ast.inParams, ['a', 'b']);
   t.deepEqual(r.ast.tasks, [
     { f: 'falpha', a: ['a', 'b'], out: ['c'], type: 'cb', name: 'falpha'}
   ]);
@@ -64,11 +64,11 @@ test('single task, single out params', function (t) {
 
 test('single task, err and out params', function (t) {
   var locals = { falpha: falpha };
-  var r = pcode('', [
+  var r = pcode('a, b', [
     'c := falpha(a, b)',
     'cb(err, c)'
   ], locals);
-  t.deepEqual(r.ast.inParams, []);
+  t.deepEqual(r.ast.inParams, ['a', 'b']);
   t.deepEqual(r.ast.tasks, [
     { f: 'falpha', a: ['a', 'b'], out: ['c'], type: 'cb', name: 'falpha'}
   ]);

package/test/validate.test.js

@@ -210,9 +210,57 @@ test('multiple tasks output the same param, must be unique', function (t) {
       { f: foo, a: [], out: ['baz', 'c'] },
       { f: bar, a: [], out: ['c'] }
     ], 
-    outTask: { a: ['bar'] }
+    outTask: { a: ['baz'] }
   };
   var msg = 'multiple tasks output the same param, must be unique. param: c';
   t.deepEqual(validate(ast), [msg]);  
   t.end();
+});
+
+test('missing or mispelled input variable', function (t) {
+  var ast = {
+    inParams: [], 
+    tasks: [
+      { f: foo, a: [], out: [] },
+      { f: bar, a: ['abc'], out: [] }
+    ], 
+    outTask: { a: [] }
+  };
+  var msg = 'missing or mispelled variable referenced in flow definition: abc';
+  t.deepEqual(validate(ast), [msg]);  
+  t.end();  
+});
+
+test('missing or mispelled input variables', function (t) {
+  var ast = {
+    inParams: ['aaa', 'bbb'], 
+    tasks: [
+      { f: foo, a: ['aaa', 'cat'], out: ['ccc'] },
+      { f: bar, a: ['abc', 'bbb', 'ccc'], out: [] }
+    ], 
+    outTask: { a: [] }
+  };
+  var messages = [
+    'missing or mispelled variable referenced in flow definition: cat',
+    'missing or mispelled variable referenced in flow definition: abc'
+  ];
+  t.deepEqual(validate(ast), messages);  
+  t.end();  
+});
+
+test('missing or mispelled final output variables', function (t) {
+  var ast = {
+    inParams: ['aaa'], 
+    tasks: [
+      { f: foo, a: ['aaa'], out: ['bbb'] },
+      { f: bar, a: ['bbb'], out: ['ccc'] }
+    ], 
+    outTask: { a: ['ccc', 'ddd', 'eee'] }
+  };
+  var messages = [
+    'missing or mispelled variable referenced in flow definition: ddd',
+    'missing or mispelled variable referenced in flow definition: eee'
+  ];
+  t.deepEqual(validate(ast), messages);  
+  t.end();  
 });