react 0.2.6 → 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,7 @@ 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

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

@@ -2,9 +2,9 @@
 /*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';
@@ -20,7 +20,7 @@ function filterOutLeadingErrParam(args) { // if leading err param, filter it out
 
 
 var inOutDefParse = {
-  regex: /^([^\-]*)(->)?\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 {
@@ -116,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

@@ -2,9 +2,9 @@
 /*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';
@@ -63,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',
@@ -77,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',
@@ -170,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,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,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() {
@@ -79,9 +102,10 @@ function reactFactory() {
     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

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-manager.js

@@ -3,12 +3,20 @@
 var EventEmitter2 = require('eventemitter2').EventEmitter2;
 
 var EVENT_EMITTER2_CONFIG = {
-  wildcard: true
+  wildcard: true, // should the event emitter use wildcards.
+  delimiter: '.', // the delimiter used to segment namespaces, defaults to `.`.
+  maxListeners: 30 // the max number of listeners that can be assigned to an event, defaults to 10.
 };
 
 var TYPES = {
-  TASK_BEGIN: 'task.begin',
-  TASK_COMPLETE: 'task.complete'
+  // Flow monitoring events and their params
+  TASK_BEGIN: 'task.begin',                        // task
+  TASK_COMPLETE: 'task.complete',                  // task
+
+  // Internal Hooks
+  EXEC_INPUT_PREPROCESS: 'exec.input.preprocess',  // parsedInput
+  EXEC_TASKS_PRECREATE: 'exec.tasks.precreate',     // taskEnv
+  EXEC_OUTTASK_CREATE: 'exec.outTask.create'      // outTaskOptions
 };
 
 /**
@@ -21,6 +29,9 @@ function EventManager() {
 
 EventManager.create = function () { return new EventManager(); };
 
+EventManager.TYPES = TYPES;
+EventManager.prototype.TYPES = TYPES;
+
 EventManager.prototype.isEnabled = function () { // if has listener or an ancestor has listener
   return (this.emitter || (this.parent && this.parent.isEnabled()));
 };
@@ -36,6 +47,7 @@ EventManager.prototype.on = function (event, listener) {
 };
 
 EventManager.prototype.emit = function (event, arg1, arg2, argN) {
+  if (event === undefined) throw new Error('event is undefined');
   if (this.emitter) this.emitter.emit.apply(this.emitter, arguments);
   if (this.parent && this.parent.isEnabled()) this.parent.emit.apply(this.parent, arguments);
 };
@@ -54,5 +66,4 @@ EventManager.prototype.emitObject = function (event, object) {
 };
 
 module.exports = EventManager;
-module.exports.TYPES = TYPES;
-module.exports.globalEventManager = EventManager.create(); // create one top level emitter
+module.exports.global = EventManager.create(); // create one top level emitter