react 0.2.3 → 0.3.0

package/README.md

@@ -40,7 +40,7 @@ It takes inspiration from several projects including:
  - object instance method calls
  - class method calls
  - selectFirst flow where the first task that returns defined, non-null value is used
- - (planned) promise style functions - also automatic resolution of promise inputs
+ - promise style functions - also automatic resolution of promise inputs (optional require('react/promise-resolve');)
  - (planned) use of resulting flow function as callback style or promise style (if no callback provided)
  - (planned) iteration on arrays, streams, sockets
  - (planned) event emitter integration
@@ -157,7 +157,7 @@ fn('foo', 'pre-', '-post', function cb(err, lres) {
 ### Example using Function String DSL interface
 
 ```javascript
-var react = require('react');
+var fstrDefine = require('react/dsl/fstr');
 
 function loadUser(uid, cb){ setTimeout(cb, 100, null, "User"+uid); }
 function loadFile(filename, cb){ setTimeout(cb, 100, null, 'Filedata'+filename); }
@@ -176,7 +176,7 @@ function useHtml(err, html, user, bytesWritten) {
   console.log('final result: %s, user: %s, written:%s', html, user, bytesWritten);
 }
 
-var loadAndSave = react.fstrDefine('filename, uid, outDirname, cb', [  // input params
+var loadAndSave = 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
@@ -195,7 +195,7 @@ loadAndSave('file.md', 100, '/tmp/foo', useHtml);  // executing the flow
 ### Example using pseudocode DSL interface
 
 ```javascript
-var react = require('react');
+var pcodeDefine = require('react/dsl/pcode');
 
 function multiply(a, b, cb) { cb(null, a * b); }
 function add(a, b) { return a + b; }
@@ -204,7 +204,7 @@ var locals = {   // since pcodeDefine uses strings, need references to functions
   add: add
 };
 
-var fn = react.pcodeDefine('a, b, cb', [  // input params
+var fn = pcodeDefine('a, b, cb', [  // input params
   'm := multiply(a, b)',   // using a callback function, use :=
   's = add(m, a)',        // using a sync function, use =
   'cb(err, m, s)'     // output params for final callback
@@ -221,12 +221,12 @@ fn(2, 3, function (err, m, s) {
 ### Example using jquery-like chaining DSL interface
 
 ```javascript
-var react = require('react');
+var chainDefine = require('react/dsl/chain');
 
 function multiply(a, b, cb) { cb(null, a * b); }
 function add(a, b) { return a + b; }
 
-var fn = react.chainDefine()
+var fn = chainDefine()
   .in('a', 'b', 'cb')                                   // input params
   .out('err', 'm', 's')                                 // final callback output params
   .async(multiply).in('a', 'b', 'cb').out('err', 'm')   // task def - async fn, in params, callback out params
@@ -242,6 +242,8 @@ fn(2, 3, function (err, m, s) {
 
 ## Status
 
+ - 2012-01-13 - Add promise tasks, promise resolution, refactor alternate DSL interfaces as optional requires (v0.3.0)
+ - 2012-01-11 - Provide warning/error when name is skipped in default DSL, literal check in validate (v0.2.5)
  - 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.
@@ -251,23 +253,23 @@ fn(2, 3, function (err, m, s) {
 ```bash
 ok ast.test.js .................... 10/10
 ok cb-task.test.js ................ 31/31
-ok chain.test.js .................. 56/56
+ok chain.test.js .................. 59/59
 ok core.test.js ................... 98/98
-ok dsl.test.js .................... 58/58
+ok dsl.test.js .................... 63/63
 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 fstr.test.js ................... 67/67
 ok input-parser.test.js ........... 15/15
 ok module-use.test.js ............. 64/64
-ok pcode.test.js .................. 65/65
+ok pcode.test.js .................. 68/68
 ok ret-task.test.js ............... 31/31
 ok task.test.js ..................... 1/1
 ok validate-cb-task.test.js ......... 6/6
 ok validate-ret-task.test.js ........ 7/7
-ok validate.test.js ............... 26/26
+ok validate.test.js ............... 31/31
 ok vcon.test.js ................... 42/42
-total ........................... 613/613
+total ........................... 632/632
 
 ok
 ```

package/{lib → dsl}/chain.js

@@ -1,8 +1,8 @@
 'use strict';
 
 var sprintf = require('sprintf').sprintf;
-var core = require('./core.js');
-var tutil = require('./task.js');
+var core = require('../lib/core.js');
+var tutil = require('../lib/task.js');
 
 // err for task type cb is implied and thus optional, but allow for clarity. 
 var ERROR_NAMES_RE = /^err$/i;  // first out param matching this is skipped as being the err object
@@ -145,4 +145,6 @@ FlowBuilder.prototype.end = function end() {
   return reactFn;
 };
 
-module.exports = chainDefine;
+module.exports = chainDefine;
+module.exports.options = core.options;
+module.exports.events = core.events;

package/{lib → dsl}/fstr.js

@@ -1,23 +1,32 @@
 '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 core = require('../lib/core.js');
+var parse = require('../lib/parse.js');
+var tutil = require('../lib/task.js');
 
 var INPARAMS_NO_MATCH = 'input params in wrong format, wanted "foo, bar" -  found: %s';
 var OUTPARAMS_NO_MATCH = 'output params in wrong format, wanted "foo, bar" - found: %s';
 var INOUT_PARAMS_NO_MATCH = 'task params in wrong format, wanted "foo, bar -> err, baz" - found: %s';
 var EXTRA_TASKARG = 'extra unmatched task arg: %s';
 
+var ERR_NAMES_RE = /^err$/i; // err, ERR, Err, ...
+
+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*(er{0,2}\s*,|returns?\s+)?(.*)$/i,
+  regex: /^([^\-]*)(->)?\s*(returns?\s+)?(.*)$/i,  //TODO this will not work if literal has dash
   fn: function (m) {
     var reMatchReturns = /returns?/i;
     return {
       type: (m[3] && m[3].match(reMatchReturns)) ? 'ret' : 'cb',
       inDef: parse.splitTrimFilterArgs(m[1]),
-      outDef: parse.splitTrimFilterArgs(m[4])
+      outDef: filterOutLeadingErrParam(parse.splitTrimFilterArgs(m[4]))
     };
   }
 };
@@ -107,4 +116,6 @@ function selectFirst(inParamStr, taskDefArr, outParamStr, options) {
 }
 
 module.exports = fstrDefine;
-module.exports.selectFirst = selectFirst;
+module.exports.selectFirst = selectFirst;
+module.exports.options = core.options;
+module.exports.events = core.events;

package/{lib → dsl}/pcode.js

@@ -1,15 +1,24 @@
 '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 core = require('../lib/core.js');
+var parse = require('../lib/parse.js');
+var tutil = require('../lib/task.js');
 
 var INPARAMS_NO_MATCH = 'input params in wrong format, wanted "foo, bar, cb" -  found: %s';
 var OUTPARAMS_NO_MATCH = 'output params in wrong format, wanted "cb(err, foo)" - found: %s';
 var INOUT_PARAMS_NO_MATCH = 'task params in wrong format, wanted "foo, bar := func(baz, cat, cb) " - found: %s';
 var EXTRA_TASKARG = 'extra unmatched task arg: %s';
 
+var ERR_NAMES_RE = /^err$/i; // err, ERR, Err, ...
+
+function filterOutLeadingErrParam(args) { // if leading err param, filter it out
+  if (args.length && args[0].match(ERR_NAMES_RE)) args.shift();
+  return args;
+}
+
+
 /**
   Examples:
   var react = require('react');
@@ -54,7 +63,7 @@ var inParse = {
 };
 
 var cbParse = {
-  regex: /^\s*(var\s+)?([^:]*)\s*:=\s*([a-zA-Z0-9_\.-]+)\s*\(\s*([^)]*)\)\s*(when\s+([^;]+))?;?\s*$/,
+  regex: /^\s*(var\s+)?([^:]*)\s*:=\s*([a-zA-Z0-9_\.\-]+)\s*\(\s*([^)]*)\)\s*(when\s+([^;]+))?;?\s*$/,
   fn: function (m) {
     var taskDef = {
       type: 'cb',
@@ -68,7 +77,7 @@ var cbParse = {
 };
 
 var retParse = {
-  regex: /^\s*(var\s+)?([^:]*)\s*=\s*([a-zA-Z0-9_\.-]+)\s*\(\s*([^)]*)\)\s*(when\s+([^;]+))?;?\s*$/,
+  regex: /^\s*(var\s+)?([^:]*)\s*=\s*([a-zA-Z0-9_\.\-]+)\s*\(\s*([^)]*)\)\s*(when\s+([^;]+))?;?\s*$/,
   fn: function (m) {
     var taskDef = {
       type: 'ret',
@@ -82,10 +91,10 @@ var retParse = {
 };
 
 var finalCbParse = {
-  regex: /^\s*(cb|callback)\s*\((er{0,2}\s*,\s*)?([^)]*)\)\s*;?$/i,
+  regex: /^\s*(cb|callback)\s*\(([^)]*)\)\s*;?$/i,
   fn: function (m) {
     return {
-      outDef: (m[3]) ? parse.splitTrimFilterArgs(m[3]) : []
+      outDef: (m[2]) ? filterOutLeadingErrParam(parse.splitTrimFilterArgs(m[2])) : []
     };
   }
 };
@@ -161,4 +170,6 @@ function selectFirst(inParamStr, taskStrArr, locals, options) {
 }
 
 module.exports = pcodeDefine;
-module.exports.selectFirst = selectFirst;
+module.exports.selectFirst = selectFirst;
+module.exports.options = core.options;
+module.exports.events = core.events;

package/examples/chain-events1.js

@@ -1,9 +1,9 @@
 'use strict';
 
-var react = require('../'); // require('react');
+var chainDefine = require('../dsl/chain'); // require('react/dsl/chain');
 
 //output events as tasks start and complete
-react.events.on('*', function (obj) {
+chainDefine.events.on('task.*', function (obj) {
   var time = new Date();
   time.setTime(obj.time);
   var eventTimeStr = time.toISOString();
@@ -20,7 +20,7 @@ react.events.on('*', function (obj) {
 function multiply(a, b, cb) { cb(null, a * b); }
 function add(a, b) { return a + b; }
 
-var fn = react.chainDefine()
+var fn = chainDefine()
   .in('a', 'b', 'cb')                                   // input params
   .out('err', 'm', 's')                                 // final callback output params
   .async(multiply).in('a', 'b', 'cb').out('err', 'm')   // task def - async fn, in params, callback out params

package/examples/chain1.js

@@ -1,11 +1,11 @@
 'use strict';
 
-var react = require('../'); // require('react');
+var chainDefine = require('../dsl/chain'); // require('react/dsl/chain');
 
 function multiply(a, b, cb) { cb(null, a * b); }
 function add(a, b) { return a + b; }
 
-var fn = react.chainDefine()
+var fn = chainDefine()
   .in('a', 'b', 'cb')                                   // input params
   .out('err', 'm', 's')                                 // final callback output params
   .async(multiply).in('a', 'b', 'cb').out('err', 'm')   // task def - async fn, in params, callback out params

package/examples/default-events1.js

@@ -4,7 +4,7 @@
 var react = require('../'); // require('react');
 
 //output events as tasks start and complete
-react.events.on('*', function (obj) {
+react.events.on('task.*', function (obj) {
   var time = new Date();
   time.setTime(obj.time);
   var eventTimeStr = time.toISOString();
@@ -43,7 +43,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/fstr-events1.js

@@ -1,9 +1,10 @@
 'use strict';
+/*jshint white: false */
 
-var react = require('../'); // require('react');
+var fstr = require('../dsl/fstr'); // require('react/dsl/fstr');
 
 //output events as tasks start and complete
-react.events.on('*', function (obj) {
+fstr.events.on('task.*', function (obj) {
   var time = new Date();
   time.setTime(obj.time);
   var eventTimeStr = time.toISOString();
@@ -34,7 +35,7 @@ function useHtml(err, html, user, bytesWritten) {
   console.log('final result: %s, user: %s, written:%s', html, user, bytesWritten);
 }
 
-var loadAndSave = react.fstrDefine('filename, uid, outDirname, cb', [  // input params
+var loadAndSave = fstr('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

package/examples/fstr1.js

@@ -1,6 +1,7 @@
 'use strict';
+/*jshint white: false */
 
-var react = require('../'); // require('react');
+var fstr = require('../dsl/fstr'); // require('react/dsl/fstr');
 
 function loadUser(uid, cb){ setTimeout(cb, 100, null, "User"+uid); }
 function loadFile(filename, cb){ setTimeout(cb, 100, null, 'Filedata'+filename); }
@@ -19,7 +20,7 @@ function useHtml(err, html, user, bytesWritten) {
   console.log('final result: %s, user: %s, written:%s', html, user, bytesWritten);
 }
 
-var loadAndSave = react.fstrDefine('filename, uid, outDirname, cb', [  // input params
+var loadAndSave = fstr('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

package/examples/pcode1.js

@@ -1,6 +1,6 @@
 'use strict';
 
-var react = require('../'); // require('react');
+var pcodeDefine = require('../dsl/pcode'); // require('react/dsl/pcode');
 
 function multiply(a, b, cb) { cb(null, a * b); }
 function add(a, b) { return a + b; }
@@ -9,7 +9,7 @@ var locals = {   // since pcodeDefine uses strings, need references to functions
   add: add
 };
 
-var fn = react.pcodeDefine('a, b, cb', [  // input params
+var fn = pcodeDefine('a, b, cb', [  // input params
   'm := multiply(a, b)',   // using a callback function, use :=
   's = add(m, a)',        // using a sync function, use =
   'cb(err, m, s)'     // output params for final callback

package/lib/base-task.js

@@ -96,6 +96,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,16 +7,25 @@ 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');
 
 var reactOptions = {
-  stackTraceLimitMin: 30  
+  stackTraceLimitMin: 30
 };
 
-var reactEmitter = EventManager.create(); // 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
@@ -39,7 +48,7 @@ var reactEmitter = EventManager.create(); // the top emitter
  */
 function reactFactory() {
   if (arguments.length) throw new Error('react() takes no args, check API');
-  
+
   error.ensureStackTraceLimitSet(reactOptions.stackTraceLimitMin);
   var flowEmitter = EventManager.create();
   flowEmitter.parent = reactEmitter;
@@ -56,18 +65,32 @@ 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
+    /*jshint validthis: true */
     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);
+    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
+    
+    var tasks = taskEnv.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(taskEnv.outTaskDef, parsedInput.cb, tasks, vCon, mergeOptions(parsedInput.options));
     var handleError = tskutil.createErrorHandler(vCon, outTask);
 
     function contExec() {
@@ -75,13 +98,14 @@ function reactFactory() {
       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
     }
-    
+
     tasks.forEach(function (t) {
       t.id = idGenerator.createUniqueId();
       t.flowEmitter = flowEmitter;
-      if (t.type === 'cb') t.cbFun = tskutil.createCallback(t, handleError, vCon, contExec, flowEmitter);
+      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