react 0.3.4 → 0.5.2

package/lib/vcon.js

@@ -71,7 +71,7 @@ VContext.create = function (args, inParams, locals, self) {
   var vContext = new VContext();
   vContext.values = args.reduce(function (vcon, x, idx) { // create vCon start with input args
     var param = inParams[idx];
-    if (param) vcon[param] = x;
+    if (param) vcon[param] = (x !== undefined) ? x : null; // upgrade undefined to null
     return vcon;
   }, initValues);
   return vContext;

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.3.4",
+  "description": "React is a javascript module implementing a lightweight rules engine 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.5.2",
   "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,7 +2,39 @@
 
 var core = require('./lib/core.js');
 
+/**
+   If called, load the built-in plugin for log events and invoke
+
+   @param flowFn [function] if not provided uses global react
+   @param eventWildcard [string] pattern to log events for
+  */
+function logEvents(flowFn, eventWildcard) {
+  var logEventsMod = require('./lib/log-events');
+  if (!eventWildcard && typeof(flowFn) === 'string') { // only wildcard provided
+    eventWildcard = flowFn;
+    flowFn = undefined;
+  } 
+  return logEventsMod.logEvents(flowFn, eventWildcard);
+}
+
+/**
+   Enable detection of promises and resolution
+  */
+function resolvePromises() {
+  require('./lib/promise-resolve');
+}
+
+/**
+   Enable tracking of tasks and flow execution, emitting events and
+   tracking start, end, elapsed time
+  */
+function trackTasks() {
+  require('./lib/track-tasks');
+}
+
 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
-
+module.exports.logEvents = logEvents;  // enable event logging
+module.exports.resolvePromises = resolvePromises; // enable promise resolution
+module.exports.trackTasks = trackTasks; // enable tracking of tasks

package/test/ast.test.js

@@ -2,7 +2,8 @@
 
 var test = require('tap').test;
 
-var react = require('../react');
+var react = require('../'); // require('react');
+var EventCollector = require('../lib/event-collector');
 
 function load(res, cb) { cb(null, res + '-loaded'); }
 function prefix(prefstr, str, cb) { cb(null, prefstr + str); }
@@ -38,6 +39,54 @@ test('mixed', function (t) {
   });
 });
 
+test('ast.defined event called when ast is defined', function (t) {
+  var fn = react();
+  var collector = new EventCollector();
+  collector.capture(fn, 'ast.*');
+  
+  var errors = fn.setAndValidateAST({
+    inParams: ['res', 'prefstr', 'poststr'],
+    tasks: [
+      { f: load,    a: ['res'],              out: ['lres'] },
+      { f: upper,   a: ['lres'],             out: ['ulres'], type: 'ret'  },
+      { f: prefix,  a: ['prefstr', 'ulres'], out: ['plres'] },
+      { f: postfix, a: ['plres', 'poststr'], out: ['plresp'] }
+    ],
+    outTask: { a: ['plresp'] }
+  });
+
+  var events = collector.list();
+  t.equal(events.length, 1);
+  t.type(events[0].ast, 'object');
+  t.ok(events[0].ast.inParams);
+  t.ok(events[0].ast.tasks);
+  t.ok(events[0].ast.outTask);
+  t.end();
+});
+
+test('ast.defined event is passed to process', function (t) {
+  t.plan(5);
+  var fn = react();
+  process.once('ast.defined', function (ast) {
+    t.type(ast, 'object');
+    t.ok(ast.inParams);
+    t.ok(ast.tasks);
+    t.ok(ast.outTask);
+    t.deepEqual(ast.inParams, ['res', 'prefstr', 'poststr']);
+    t.end();
+  });
+  var errors = fn.setAndValidateAST({
+    inParams: ['res', 'prefstr', 'poststr'],
+    tasks: [
+      { f: load,    a: ['res'],              out: ['lres'] },
+      { f: upper,   a: ['lres'],             out: ['ulres'], type: 'ret'  },
+      { f: prefix,  a: ['prefstr', 'ulres'], out: ['plres'] },
+      { f: postfix, a: ['plres', 'poststr'], out: ['plresp'] }
+    ],
+    outTask: { a: ['plresp'] }
+  });
+});
+
 test('cb with err', function (t) {
   t.plan(5);
   

package/test/core.test.js

@@ -3,13 +3,14 @@
 var test = require('tap').test;
 
 var react = require('../react');
-var EventCollector = require('../lib/track-tasks').EventCollector;  // require('react/lib/track-tasks'); // turn on tracking
+var EventCollector = require('../lib/event-collector');  // require('react/lib/event-collector'); // turn on tracking and get EventCollector
 
 function multiply(x, y, cb) { cb(null, x * y); }
 function add(x, y, cb) { cb(null, x + y); }
 function badFunc(a, b, cb) { throw new Error('badFuncThrow'); }
 function badF2(a, b, cb) { cb('my-error'); }
 function fnRetsSum(a, b) { return a + b; }
+var anonFn = function (a, b) { return a + b; };
 
 test('set and validate AST', function (t) {
   var fn = react();
@@ -42,16 +43,19 @@ test('unnamed tasks will be assigned unique names', function (t) {
       { f: multiply, a: ['a', 'b'], out: ['c'] },
       { f: multiply, a: ['a', 'b'], out: ['d'], name: 'multiply' },
       { f: multiply, a: ['a', 'b'], out: ['e'], name: 'times' },
+      { f: anonFn,   a: ['a', 'b'], out: ['g'], type: 'ret' },
       { f: multiply, a: ['a', 'b'], out: ['f'] }
     ],
     outTask: { a: ['c'] }
   });
   t.deepEqual(errors, [], 'should set and validate as true');
+  t.equal(fn.ast.name.slice(0, 'flow_'.length), 'flow_', 'generated flow name should start with flow_');
   t.deepEqual(fn.ast.tasks, [
       { f: multiply, a: ['a', 'b'], out: ['c'], type: 'cb', name: 'multiply_0' },
       { f: multiply, a: ['a', 'b'], out: ['d'], name: 'multiply', type: 'cb' },
       { f: multiply, a: ['a', 'b'], out: ['e'], name: 'times', type: 'cb' },
-      { f: multiply, a: ['a', 'b'], out: ['f'], type: 'cb', name: 'multiply_3' }
+      { f: anonFn,   a: ['a', 'b'], out: ['g'], type: 'ret', name: 'task_3' },    
+      { f: multiply, a: ['a', 'b'], out: ['f'], type: 'cb', name: 'multiply_4' }
     ]);
   t.end();
 });
@@ -431,6 +435,27 @@ test('using "this" in a sync function', function (t) {
   }]);
 });
 
+test('undefined input arguments will be upgraded from undefined to null', function (t) {
+  var fn = react();
+  function concat(a, b) {
+    return '' + a + b;    
+  }
+  var errors = fn.setAndValidateAST({
+    inParams: ['a', 'b'],
+    tasks: [
+      { f: concat, a: ['a', 'b'], out: ['c'], type: 'ret' }
+    ],
+    outTask: { a: ['c'] }
+  });
+  t.deepEqual(errors, [], 'no validation errors');
+  fn('first', undefined, function (err, c) {  // undefined second param, upgrade to null
+    t.equal(err, null);
+    t.equal(c, 'firstnull');
+    t.end();
+  });
+});
+
+
 
 // Select first tests
 

package/test/dsl.test.js

@@ -16,7 +16,7 @@ test('module exports is a fn with properties', function (t) {
 
 test('no arguments -> empty name, inParams, tasks, outTask', function (t) {
   var r = react();
-  t.equal(r.ast.name, undefined);
+  t.equal(r.ast.name.slice(0, 'flow_'.length), 'flow_', 'generated flow name should start with flow_');
   t.deepEqual(r.ast.inParams, []);
   t.deepEqual(r.ast.tasks, []);
   t.deepEqual(r.ast.outTask, { a: [], type: 'finalcb' });
@@ -26,7 +26,7 @@ test('no arguments -> empty name, inParams, tasks, outTask', function (t) {
 
 test('empty first string -> empty name, inParams, tasks, outTask', function (t) {
   var r = react('');
-  t.equal(r.ast.name, '');
+  t.equal(r.ast.name.slice(0, 'flow_'.length), 'flow_', 'generated flow name should start with flow_');
   t.deepEqual(r.ast.inParams, []);
   t.deepEqual(r.ast.tasks, []);
   t.deepEqual(r.ast.outTask, { a: [], type: 'finalcb' });

package/test/module-use.test.js

@@ -4,8 +4,8 @@ var test = require('tap').test;
 var BaseTask = require('../lib/base-task.js');
 
 var react = require('../'); // require('react');
-// turn on tracking, optionally obtain EventCollector
-var EventCollector = require('../lib/track-tasks').EventCollector;  // require('react/lib/track-tasks'); 
+// turn on tracking, obtain EventCollector
+var EventCollector = require('../lib/event-collector');  // require('react/lib/event-collector'); 
 
 
 /**
@@ -39,6 +39,9 @@ test('module exports an function object with properties', function (t) {
   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.events, 'object', 'has global react event manager');
+  t.type(react.logEvents, 'function', 'has function to enable event logging');
+  t.type(react.trackTasks, 'function', 'has function to enable task and flow tracking');
+  t.type(react.resolvePromises, 'function', 'has fn to enable promise detection & resolution');
   t.end();
 });
 

package/test/promise-auto-resolve.test.js

@@ -8,7 +8,8 @@
 var test = require('tap').test;
 var Deferred = require('promised-io/promise').Deferred;
 
-var react = require('../promise-resolve');  // require('react/promise-resolve');
+var react = require('../');  // require('react');
+react.resolvePromises(); // enable promise resolving
 
 function multiply(x, y, cb) { cb(null, x * y); }
 function add(x, y, cb) { cb(null, x + y); }

package/Jakefile.js

@@ -1,8 +0,0 @@
-
-
-require('./jake-tasks/jake-test.js');
-
-desc('Default - run watch');
-task('default', ['test:watch']);
-
-

package/doc/alternate-dsls.md

@@ -1,103 +0,0 @@
-# Alternate DSL's
-
-These DSL's are not loaded by default and thus require a separate require if you want to use one.
-
-Since React is an AST based rules system, it allows custom DSL's to be created easily, they only need to generate the AST and they are fully functional, allowing many different interfaces for the same system.
-
-
-### Examples using the AST directly or alternate DSL's
-
-
- 1. [Using pseudocode DSL](#pcode)
- 2. [Using jquery-like chaining DSL](#chain)
- 3. [Function String DSL](#fstr)  (Deprecated)
-
-
-<a name="pcode"/>
-### Example using pseudocode DSL interface
-
-```javascript
-var pcodeDefine = require('react/dsl/pcode');
-
-function multiply(a, b, cb) { cb(null, a * b); }
-function add(a, b) { return a + b; }
-var locals = {   // since pcodeDefine uses strings, need references to functions passed into react
-  multiply: multiply,
-  add: add
-};
-
-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
-], locals);    // hash of functions that will be used
-
-fn(2, 3, function (err, m, s) {
-  console.error('err:', err); // null
-  console.error('m:', m);  // 2 * 3 = 6
-  console.error('s:', s);  // 6 + 2 = 8
-});
-```
-
-<a name="chain"/>
-### Example using jquery-like chaining DSL interface
-
-```javascript
-var chainDefine = require('react/dsl/chain');
-
-function multiply(a, b, cb) { cb(null, a * b); }
-function add(a, b) { return a + b; }
-
-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
-  .sync(add).in('m', 'a').out('s')                      // task def - sync fn, in params, return value
-  .end();
-
-fn(2, 3, function (err, m, s) {
-  console.error('err:', err); // null
-  console.error('m:', m);  // 2 * 3 = 6
-  console.error('s:', s);  // 6 + 2 = 8
-});
-```
-
-<a name="fstr"/>
-### Example using Function String DSL interface
-
-The Function String DSL interface is deprecated since it morphed into the default DSL which is very similar. It is recommended that you use the default DSL instead.
-
-```javascript
-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); }
-function markdown(filedata) { return 'html'+filedata; }
-function prepareDirectory(outDirname, cb){ setTimeout(cb, 200, null, 'dircreated-'+outDirname); }
-function writeOutput(html, user, cb){  setTimeout(cb, 300, null, html+'_bytesWritten'); }
-function loadEmailTemplate(cb) { setTimeout(cb, 50, null, 'emailmd'); }
-function customizeEmail(user, emailHtml, cb) { return 'cust-'+user+emailHtml; }
-function 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 = fstrDefine('filename, uid, outDirname, cb', [  // input params
-  loadUser,         'uid              -> err, user',     // calling async fn loadUser with uid, callback is called with err and user
-  loadFile,         'filename         -> err, filedata',
-  markdown,         'filedata         -> returns html',    // using a sync function
-  prepareDirectory, 'outDirname       -> err, dircreated',
-  writeOutput,      'html, user       -> err, bytesWritten', { after: prepareDirectory },  // only after prepareDirectory done
-  loadEmailTemplate, '                 -> err, emailmd',
-  markdown,         'emailmd          -> returns emailHtml',   // using a sync function
-  customizeEmail,   'user, emailHtml  -> returns custEmailHtml',
-  deliverEmail,     'custEmailHtml    -> err, deliveredEmail', { after: writeOutput }  // only after writeOutput is done
-], 'err, html, user, bytesWritten');   // callback output params
-
-loadAndSave('file.md', 100, '/tmp/foo', useHtml);  // executing the flow
-```

package/dsl/chain.js

@@ -1,150 +0,0 @@
-'use strict';
-
-var sprintf = require('sprintf').sprintf;
-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
-
-// callback is implied for task type cb is implied and thus optional, but allow for clarity. 
-var CALLBACK_NAMES_RE = /^cb$|^callback$/i;  // last in param matching this is skipped as being the cb
-
-var FlowBuilder;
-
-/**
-   jQuery-like chain interface for defining flow
-
-   @example
-    // normal flow
-    var react = require('react');
-    var fn = react.chainDefine()
-      .in('filename', 'uid', 'outDirname', 'cb')
-      .out('err', 'html', 'user', 'bytesWritten')  
-      .async(loadUser)          .in('uid')               .out('err', 'user')
-      .async(loadFile)          .in('filename')          .out('err', 'filedata')
-      .sync(markdown)           .in('filedata')          .out('html')
-      .async(prepareDirectory)  .in('outDirname')        .out('err', 'dircreated') 
-      .async(writeOutput)       .in('html', 'user')      .out('err', 'bytesWritten')   .after('prepareDirectory')
-      .async(loadEmailTemplate) .in()                    .out('err', 'emailmd')
-      .sync(markdown)           .in('emailmd')           .out('emailHtml')
-      .sync(customizeEmail)     .in('user', 'emailHtml') .out('custEmailHtml')
-      .async(deliverEmail)      .in('custEmailHtml')     .out('err', 'deliveredEmail') .after('writeOutput')
-      .end();
-
-   @example
-    // selectFirst flow
-    var fn = chainDefine()
-      .selectFirst()
-      .in('a', 'b', 'cb')
-      .out('err', 'c')
-      .async(falpha).in('a', 'b', 'cb').out('err', 'c')
-      .sync(fbeta).in('a', 'b').out('c')
-      .end();    
-*/
-function chainDefine() {
-  return FlowBuilder.create();
-}
-
-function FlowBuilder() {
-  this.main = {
-    name: null,
-    options: {}
-  };
-  this.tasks = [];
-  this.focus = this.main;
-}
-
-FlowBuilder.create = function () { return new FlowBuilder(); };
-
-FlowBuilder.prototype.selectFirst = function () {
-  this.main.outTaskType = 'finalcbFirst';
-  return this;
-};
-
-FlowBuilder.prototype.name = function (name) {
-  this.focus.name = name;
-  return this;
-};
-
-FlowBuilder.prototype.in = function (param1, param2, paramN) { 
-  var args = Array.prototype.slice.call(arguments);
-  if (args.length && this.focus.type !== 'ret') {  // has args and cb or main
-    if (args[args.length - 1].match(CALLBACK_NAMES_RE)) args.pop(); // pop off the cb name if specified
-  }
-  if (this.focus === this.main) this.focus.in = args;
-  else this.focus.a = args;   // for tasks
-  return this;
-};
-
-FlowBuilder.prototype.out = function (param1, param2, paramN) {
-  var args = Array.prototype.slice.call(arguments);
-  if (args.length && this.focus.type !== 'ret') {  // has args and cb or main
-    if (args[0].match(ERROR_NAMES_RE)) args.shift(); // shift off err if specified
-  }
-  this.focus.out = args;
-  return this;
-};
-
-FlowBuilder.prototype.options = function (options) {
-  var self = this;
-  if (this.focus === this.main) {
-    Object.keys(options).forEach(function (k) { self.focus.options[k] = options[k]; });
-  } else { // task so set options right on task
-    Object.keys(options).forEach(function (k) { self.focus[k] = options[k]; });
-  }
-  return this;
-};
-
-FlowBuilder.prototype.async = function (funcOrStrMethod) {
-  var task = { f: funcOrStrMethod, type: 'cb' };
-  this.tasks.push(task);
-  this.focus = task;
-  return this;
-};
-
-FlowBuilder.prototype.sync = function (funcOrStrMethod) {
-  var task = { f: funcOrStrMethod, type: 'ret' };
-  this.tasks.push(task);
-  this.focus = task;
-  return this;
-};
-
-FlowBuilder.prototype.after = function (name1, name2, nameN) {
-  this.focus.after = Array.prototype.slice.call(arguments);
-  return this;
-};
-
-/**
-   Complete the building of a flow and perform validation
-   which throws error if flow is not valid.
-  */
-FlowBuilder.prototype.end = function end() {
-  var reactFn = core();
-
-  if (this.main.outTaskType === 'finalcbFirst') {
-    this.tasks = tutil.serializeTasks(this.tasks);
-  }
-
-  var ast = {
-    inParams: this.main.in || [],
-    tasks: this.tasks,
-    outTask: {
-      a: this.main.out || [],
-      type: this.main.outTaskType || 'finalcb'
-    }
-  };
-  if (this.main.name) ast.name = this.main.name;
-  var self = this;
-  Object.keys(this.main.options).forEach(function (k) { ast[k] = self.main.options[k]; });
-  var errors = reactFn.setAndValidateAST(ast);
-  if (errors.length) {
-    var errorStr = errors.join('\n');
-    throw new Error(errorStr);
-  }
-  return reactFn;
-};
-
-module.exports = chainDefine;
-module.exports.options = core.options;
-module.exports.events = core.events;