react 0.3.5 → 0.5.0

package/examples/default-log-events.js

@@ -6,7 +6,7 @@
   */
 
 var react = require('../'); // require('react');
-require('../lib/log-events').logEvents(react);  // require('react/lib/log-events').logEvents(react); // turn on logging
+react.logEvents(); // turn on logging of all flow and task events for all react functions
 
 
 function loadUser(uid, cb){ setTimeout(cb, 100, null, "User"+uid); }

package/lib/event-collector.js

@@ -0,0 +1,65 @@
+'use strict';
+
+var react = require('../');  // require('react');
+react.trackTasks(); // enable task tracking
+
+var TASK_EVENTS_RE = /^task\./;
+var FLOW_EVENTS_RE = /^flow\./;
+
+/**
+   Accumulator to make it easy to capture events
+
+   @example
+   var EventCollector = require('react/lib/event-collector');
+   var collector = new EventCollector();
+
+   collector.capture(); // capture all flow and task events for all react flows
+   collector.capture('flow.*'); // capture all flow events for all react flows
+   collector.capture(flowFn, 'task.*'); // capture task events on a flow
+   collector.capture(flowFn, 'flow.*'); // add capture flow events on a flow
+
+   var events = collector.list();  // retrieve the list of events
+   collector.clear();  // clear the list of events;
+*/
+function EventCollector() {
+  this.events = [];
+}
+
+/**
+   register listener to capture events for a specific flow
+   @param flowFn the react flow function or can pass global react
+   @param eventId event id or wildcarded id
+  */
+EventCollector.prototype.capture = function (flowFn, eventId) {
+  /*jshint validthis: true */
+  if (!eventId && typeof(flowFn) === 'string') { // only eventId provided
+    eventId = flowFn;
+    flowFn = react; // global react
+  } else if (!flowFn) flowFn = react; // global react
+  if (!eventId) eventId = '*'; // default to all
+  var emitter = flowFn.events;
+  var self = this;
+  function accumEvents(obj) {
+    var eventObject = {
+      event: this.event,
+      time: Date.now()
+    };
+    if (FLOW_EVENTS_RE.test(this.event)) {
+      eventObject.env = obj;
+    } else if (TASK_EVENTS_RE.test(this.event)) {
+      eventObject.task = obj;
+    }
+    self.events.push(eventObject);      
+  }
+  emitter.on(eventId, accumEvents);
+};
+
+EventCollector.prototype.list = function () {
+  return this.events;
+};
+
+EventCollector.prototype.clear = function () {
+  this.events = []; // clear
+};
+
+module.exports = EventCollector;

package/lib/log-events.js

@@ -5,13 +5,20 @@
 
    @example
    var react = require('react');
-   require('react/lib/log-events').logEvent(react);
+   react.logEvents(); // log all task and flow events on all react functions
+   react.logEvents('task.*'); // log all task events on all react functions
+   react.logEvents(flowFn); // log all task and flow events on flowFn only
+   react.logEvents(flowFn, 'flow.*'); // log all flow events on flowFn only
   */
 
-var react = require('../lib/track-tasks');  // require('react/lib/track-tasks'); // turn on tracking
+var util = require('util'); // TODO replace inspect with something portable to browser
+
+var react = require('../'); // require('react');
+react.trackTasks(); // enable task and flow tracking
 
 var ALL_FLOW_EVENTS = 'flow.*';
 var ALL_TASK_EVENTS = 'task.*';
+var FLOW_RE = /^flow\./;
 
 function flowLog(obj) {
   /*jshint validthis: true */
@@ -21,12 +28,12 @@ function flowLog(obj) {
   var eventTimeStr = time.toISOString();
   if (this.event === 'flow.complete') {
     var env = obj; 
-    console.error('%s: %s \tmsecs:(%s) \n\targs:(%s) \n\tresults:(%s)\n',
-                  this.event, env.name, env.elapsedTime, argsNoCb, env.results);   
+    console.error('%s: %s \tmsecs: %s \n\targs: %s \n\tresults: %s\n',
+                  this.event, env.name, env.elapsedTime, util.inspect(argsNoCb), util.inspect(env.results));   
   } else {
     var name = obj.name;
     var args = obj.args;
-    console.error('%s: %s \n\targs:(%s)\n', this.event, name, argsNoCb);
+    console.error('%s: %s \n\targs: %s\n', this.event, name, util.inspect(argsNoCb));
   }    
 }
 
@@ -38,12 +45,12 @@ function taskLog(obj) {
   var eventTimeStr = time.toISOString();
   if (this.event === 'task.complete') {
     var task = obj;
-    console.error('%s: %s \tmsecs:(%s) \n\targs:(%s) \n\tresults:(%s)\n',
-                  this.event, task.name, task.elapsedTime, argsNoCb, task.results);
+    console.error('%s: %s \tmsecs: %s \n\targs: %s \n\tresults: %s\n',
+                  this.event, task.name, task.elapsedTime, util.inspect(argsNoCb), util.inspect(task.results));
   } else {
     var name = obj.name;
     var args = obj.args;
-    console.error('%s: %s \n\targs:(%s)\n', this.event, name, argsNoCb);
+    console.error('%s: %s \n\targs: %s\n', this.event, name, util.inspect(argsNoCb));
   }
   
 }
@@ -55,16 +62,24 @@ function taskLog(obj) {
    
    @example
    var react = require('react');
-   require('react/lib/log-events').logEvents(flowFn); // pass flowFn or react
+   react.logEvents(flowFn, eventWildcard); //log events on flowfn matching wildcard
    
    @param flowFn Flow function or global react object
+   @param eventWildcard wildcarded event type, if not provided use flow.* and task.*
   */
-function logEvents(flowFn) {
-  //output events as tasks start and complete
-  flowFn.events.removeListener(ALL_FLOW_EVENTS, flowLog);
-  flowFn.events.on(ALL_FLOW_EVENTS, flowLog);
-  flowFn.events.removeListener(ALL_TASK_EVENTS, taskLog);
-  flowFn.events.on(ALL_TASK_EVENTS, taskLog);
+function logEvents(flowFn, eventWildcard) {
+  if (!flowFn) flowFn = react; // use global 
+  if (eventWildcard && eventWildcard !== '*') {
+    var logFn = (FLOW_RE.test(eventWildcard)) ? flowLog : taskLog;
+    flowFn.events.removeListener(eventWildcard, logFn);
+    flowFn.events.on(eventWildcard, logFn);
+  } else { // none provided, use flow.* and task.*
+    //output events as tasks start and complete
+    flowFn.events.removeListener(ALL_FLOW_EVENTS, flowLog);
+    flowFn.events.on(ALL_FLOW_EVENTS, flowLog);
+    flowFn.events.removeListener(ALL_TASK_EVENTS, taskLog);
+    flowFn.events.on(ALL_TASK_EVENTS, taskLog);      
+  }
 }
 
 module.exports = react;

package/{promise-resolve.js → lib/promise-resolve.js}

@@ -10,7 +10,7 @@
   */
 
 
-var react = require('./');  // require('react');
+var react = require('../');  // require('react');
 
 var PROMISE_SUFFIX = '__promise';  // added to param names that are promises
 

package/lib/track-tasks.js

@@ -13,68 +13,14 @@
     - emits task.complete with task
     - emits flow complete with flowEnv
     - emits flow errored with flowEnv
-  */
-
-
-var react = require('../');  // require('react');
-
-var TASK_EVENTS_RE = /^task\./;
-var FLOW_EVENTS_RE = /^flow\./;
-
-/**
-   Accumulator to make it easy to capture events
-
-   @example
-   var EventCollector = require('react/lib/track-tasks').EventCollector;
-   var collector = new EventCollector();
-   
-   collector.captureGlobal('*'); // capture all react events for all flows
-
-   // OR
-   
-   collector.capture(flowFn, 'task.'); // capture task events on a flow
-   collector.capture(flowFn, 'flow.'); // add capture flow events on a flow
 
-   var events = collector.list();  // retrieve the list of events
+    @example
+    var react = require('react');
+    react.trackTasks(); // enable task and flow tracking
   */
-function EventCollector() {
-  this.events = [];
-}
 
-/**
-   register listener to capture all events
-   @param eventId event id or wildcarded id
-  */
-EventCollector.prototype.captureGlobal = function (eventId) {
-  this.capture(react, eventId);
-};
-
-/**
-   register listener to capture events for a specific flow
-   @param flowFn the react flow function or can pass global react
-   @param eventId event id or wildcarded id
-  */
-EventCollector.prototype.capture = function (flowFn, eventId) {
-  var emitter = flowFn.events;
-  var self = this;
-  function accumEvents(obj) {
-    var eventObject = {
-      event: this.event,
-      time: Date.now()
-    };
-    if (FLOW_EVENTS_RE.test(this.event)) {
-      eventObject.env = obj;
-    } else if (TASK_EVENTS_RE.test(this.event)) {
-      eventObject.task = obj;
-    }
-    self.events.push(eventObject);      
-  }
-  emitter.on(eventId, accumEvents);
-};
 
-EventCollector.prototype.list = function () {
-  return this.events;
-};
+var react = require('../');  // require('react');
 
 react.events.on(react.events.TYPES.EXEC_FLOW_START, function (env){
   env.startTime = Date.now();
@@ -111,7 +57,4 @@ react.events.on(react.events.TYPES.EXEC_FLOW_ERRORED, function (env) {
 });
 
 
-
-
 module.exports = react;  // return react
-module.exports.EventCollector = EventCollector;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "react",
   "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.3.5",
+  "version": "0.5.0",
   "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/core.test.js

@@ -3,7 +3,7 @@
 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); }

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
-```