npm - react - Versions diffs - 0.3.0 → 0.5.1 - Mend

react 0.3.0 → 0.5.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (44) hide show

package/.npmignore +2 -1
package/README.md +99 -155
package/doc/advanced.md +166 -0
package/doc/color-def.graffle +938 -0
package/doc/color-def.png +0 -0
package/doc/default-simple.dot +19 -0
package/doc/default-simple.dot.png +0 -0
package/examples/{default1.js → longer-example.js} +0 -0
package/examples/simple.js +45 -0
package/examples/{ast1.js → using-ast-directly.js} +4 -0
package/examples/using-events1.js +79 -0
package/examples/{default-events1.js → using-log-events.js} +5 -14
package/lib/base-task.js +7 -6
package/lib/core.js +33 -14
package/lib/event-collector.js +68 -0
package/lib/event-manager.js +16 -13
package/lib/finalcb-first-task.js +14 -11
package/lib/finalcb-task.js +15 -11
package/lib/id.js +1 -0
package/lib/log-events.js +86 -0
package/{promise-resolve.js → lib/promise-resolve.js} +5 -5
package/lib/task.js +18 -8
package/lib/track-tasks.js +60 -0
package/lib/vcon.js +1 -1
package/package.json +2 -2
package/react.js +33 -1
package/test/ast.test.js +27 -1
package/test/core.test.js +71 -57
package/test/dsl.test.js +2 -2
package/test/module-use.test.js +14 -9
package/test/promise-auto-resolve.test.js +2 -1
package/Jakefile.js +0 -8
package/dsl/chain.js +0 -150
package/dsl/fstr.js +0 -121
package/dsl/pcode.js +0 -175
package/examples/chain-events1.js +0 -34
package/examples/chain1.js +0 -19
package/examples/fstr-events1.js +0 -52
package/examples/fstr1.js +0 -37
package/examples/pcode1.js +0 -22
package/jake-tasks/jake-test.js +0 -64
package/test/dsl/chain.test.js +0 -323
package/test/dsl/fstr.test.js +0 -300
package/test/dsl/pcode.test.js +0 -456

package/doc/color-def.png ADDED Viewed

Binary file

package/doc/default-simple.dot ADDED Viewed

@@ -0,0 +1,19 @@
+digraph simple {
+  inputs [shape=box];
+  loadFoo [shape=box];
+  loadBar [shape=box];
+  render [shape=box];
+  outputs[shape=box];
+  inputs -> fooPath;
+  inputs -> barPath;
+  inputs -> barP2;
+  fooPath -> loadFoo;
+  loadFoo -> foo;
+  barPath -> loadBar;
+  loadBar -> bar;
+  barP2 -> loadBar;
+  foo -> render;
+  bar -> render;
+  render -> renderedOut;
+  renderedOut -> outputs;
+}

package/doc/default-simple.dot.png ADDED Viewed

Binary file

package/examples/{default1.js → longer-example.js} RENAMED Viewed

File without changes

package/examples/simple.js ADDED Viewed

@@ -0,0 +1,45 @@
+'use strict';
+/**
+   Simple example showing flow definition of two async functions feeding a
+   synchronous function.
+   First two async functions inputs are satisfied by the flow inputs, so
+   they will both run immediately in parallel.
+   The last function waits for the outputs of the previous ones, then
+   executes synchronously.
+   Finally the flow calls the callback with the output values once all
+   the tasks have completed.
+  */
+var react = require('../'); // require('react');
+function loadFoo(fooPath, cb) {
+  setTimeout(function () {
+    cb(null, [fooPath, 'data'].join(':'));
+  }, 10);
+}
+function loadBar(barPath, barP2, cb) {
+  setTimeout(function () {
+    cb(null, [barPath, barP2, 'data'].join(':'));
+  }, 10);
+}
+function render(foo, bar) {
+  return ['<html>', foo, '/', bar, '</html>'].join('');
+}
+var fn = react('loadRender', 'fooPath, barPath, barP2, cb -> err, renderedOut',
+  loadFoo, 'fooPath, cb -> err, foo',
+  loadBar, 'barPath, barP2, cb -> err, bar',
+  render, 'foo, bar -> renderedOut'
+);
+fn('foo.txt', 'bar.txt', 'BBB', function (err, renderedOut) {
+  console.error('results:', renderedOut);
+});

package/examples/{ast1.js → using-ast-directly.js} RENAMED Viewed

@@ -1,5 +1,9 @@
 'use strict';
+/**
+   Advanced example using the AST directly which most users will not do.
+   For general use, see other examples like simple.js
+  */
 var react = require('../'); // require('react');
 function load(res, cb) { setTimeout(cb, 100, null, res + '-loaded'); }

package/examples/using-events1.js ADDED Viewed

@@ -0,0 +1,79 @@
+'use strict';
+/*jshint white: false */
+/**
+   Default DSL, showing use of events
+  */
+var react = require('../'); // require('react');
+require('../lib/track-tasks');  // require('react/lib/track-tasks'); // turn on tracking
+//output events as tasks start and complete
+react.events.on('flow.*', function (obj) {
+  /*jshint validthis: true */
+  var time = new Date();
+  time.setTime(obj.time);
+  var argsNoCb = obj.args.filter(function (a) { return (typeof(a) !== 'function'); });
+  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);
+  } else {
+    var name = obj.name;
+    var args = obj.args;
+    console.error('%s: %s \n\targs:(%s)\n', this.event, name, argsNoCb);
+  }
+});
+react.events.on('task.*', function (obj) {
+  /*jshint validthis: true */
+  var time = new Date();
+  time.setTime(obj.time);
+  var argsNoCb = obj.args.filter(function (a) { return (typeof(a) !== 'function'); });
+  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);
+  } else {
+    var name = obj.name;
+    var args = obj.args;
+    console.error('%s: %s \n\targs:(%s)\n', this.event, 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  -> 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/{default-events1.js → using-log-events.js} RENAMED Viewed

@@ -1,22 +1,13 @@
 'use strict';
 /*jshint white: false */
+/**
+   Default DSL, showing use of events
+  */
 var react = require('../'); // require('react');
+react.logEvents(); // turn on logging of all flow and task events for all react functions
-//output events as tasks start and complete
-react.events.on('task.*', 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); }

package/lib/base-task.js CHANGED Viewed

@@ -19,17 +19,18 @@ BaseTask.prototype.isComplete = function () {
 };
 BaseTask.prototype.start = function (args) { // mark task as started with args and note time
+  /*jshint validthis: true */
   this.args = args;
-  this.startTime = Date.now();
-  if (this.flowEmitter) this.flowEmitter.emitObject(EventManager.TYPES.TASK_BEGIN, this);
+  this.env.currentTask = this;
+  this.env.flowEmitter.emit(EventManager.TYPES.EXEC_TASK_START, this);
 };
 BaseTask.prototype.complete = function (args) { //args that were used are available
-  this.results = args;  // save the results
-  this.endTime = Date.now();
-  this.elapsedTime = this.endTime - this.startTime;
-  if (this.flowEmitter) this.flowEmitter.emitObject(EventManager.TYPES.TASK_COMPLETE, this);
+/*jshint validthis: true */
   this.status = STATUS.COMPLETE;
+  this.results = args;
+  this.env.currentTask = this;
+  this.env.flowEmitter.emit(EventManager.TYPES.EXEC_TASK_COMPLETE, this);
 };
 BaseTask.prototype.functionExists = function (vCon) {

package/lib/core.js CHANGED Viewed

@@ -10,6 +10,7 @@ var VContext = require('./vcon.js');
 var EventManager = require('./event-manager.js');
 var inputParser = require('./input-parser.js');
 var idGenerator = require('./id.js');
+var sprintf = require('sprintf').sprintf;
 var reactOptions = {
   stackTraceLimitMin: 30
@@ -27,6 +28,13 @@ function mergeOptions(parsedOptions) {
   }, parsedOptions);
 }
+/**
+   generate a flow name when one is not provided
+  */
+function generateFlowName() {
+  return sprintf('flow_%s', idGenerator.createUniqueId());
+}
 /**
    Creates react function which the AST can be manipulated and then
    is ready to be executed. Can be used directly or a DSL can wrap this
@@ -64,44 +72,55 @@ function reactFactory() {
   function setAndValidateAST(newAST) { //set AST then validate, ret error[]
     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 (!errors.length) {
+      if (!ast.name) ast.name = generateFlowName();
+      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);
     }
+    flowEmitter.emit(EventManager.TYPES.AST_DEFINED, ast);
     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 = Array.prototype.slice.call(arguments);
+    var env = {
+      execId: idGenerator.createUniqueId(),
+      args: args,
+      ast: ast,
+      flowEmitter: flowEmitter
+    };
+    env.name = ast.name || env.execId;
+    flowEmitter.emit(EventManager.TYPES.EXEC_FLOW_START, env);  // hook
+    var parsedInput = inputParser(args, ast);
     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
+    env.parsedInput = parsedInput;
+    env.options = mergeOptions(parsedInput.options);
+    env.vCon = vCon;
+    env.taskDefs = ast.tasks.slice(); // create copy
+    env.outTaskDef = Object.create(ast.outTask); // create copy
+    reactEmitter.emit(EventManager.TYPES.EXEC_TASKS_PRECREATE, env);  // hook
-    var tasks = taskEnv.taskDefs.map(tskutil.create);
+    var tasks = env.taskDefs.map(tskutil.create);
     var tasksByName = tskutil.nameTasks(tasks); // map names to working tasks
-    var outTask = tskutil.createOutTask(taskEnv.outTaskDef, parsedInput.cb, tasks, vCon, mergeOptions(parsedInput.options));
+    var outTask = tskutil.createOutTask(env.outTaskDef, parsedInput.cb, tasks, vCon, env.options, env);
     var handleError = tskutil.createErrorHandler(vCon, outTask);
     function contExec() {
       if (!outTask.f) { return; } //stop execution, we already hit an error, f was cleared
       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
+      tskutil.findReadyAndExec(vCon, tasks, tasksByName, handleError, contExec, env);  //exec tasks that ready to run
     }
     tasks.forEach(function (t) {
       t.id = idGenerator.createUniqueId();
-      t.flowEmitter = flowEmitter;
+      t.env = env;
       if (t.prepare) t.prepare(handleError, vCon, contExec, flowEmitter);
     }); // create callbacks
     contExec();   // start things off

package/lib/event-collector.js ADDED Viewed

@@ -0,0 +1,68 @@
+'use strict';
+var react = require('../');  // require('react');
+react.trackTasks(); // enable task tracking
+var AST_EVENTS_RE = /^ast\./;
+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;
+    } else if (AST_EVENTS_RE.test(this.event)) {
+      eventObject.ast = 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/event-manager.js CHANGED Viewed

@@ -10,13 +10,24 @@ var EVENT_EMITTER2_CONFIG = {
 var TYPES = {
   // Flow monitoring events and their params
+  AST_DEFINED: 'ast.defined',                      // ast
+  FLOW_BEGIN: 'flow.begin',                        // env
   TASK_BEGIN: 'task.begin',                        // task
   TASK_COMPLETE: 'task.complete',                  // task
+  TASK_ERRORED: 'task.errored',                    // task
+  FLOW_COMPLETE: 'flow.complete',                  // env
+  FLOW_ERRORED: 'flow.errored',                    // env
   // Internal Hooks
+  EXEC_FLOW_START: 'exec.flow.start',              // env
   EXEC_INPUT_PREPROCESS: 'exec.input.preprocess',  // parsedInput
-  EXEC_TASKS_PRECREATE: 'exec.tasks.precreate',     // taskEnv
-  EXEC_OUTTASK_CREATE: 'exec.outTask.create'      // outTaskOptions
+  EXEC_TASKS_PRECREATE: 'exec.tasks.precreate',    // env
+  EXEC_OUTTASK_CREATE: 'exec.outTask.create',      // outTaskOptions
+  EXEC_TASK_START: 'exec.task.start',              // task
+  EXEC_TASK_COMPLETE: 'exec.task.complete',        // task
+  EXEC_TASK_ERRORED: 'exec.task.errored',          // task
+  EXEC_FLOW_COMPLETE: 'exec.flow.complete',        // env
+  EXEC_FLOW_ERRORED: 'exec.flow.errored'           // env
 };
 /**
@@ -52,18 +63,10 @@ EventManager.prototype.emit = function (event, arg1, arg2, argN) {
   if (this.parent && this.parent.isEnabled()) this.parent.emit.apply(this.parent, arguments);
 };
-/**
-   Emit an object augmented with standard fields.
-   Copies object and adds standard fields:
-    event: event type
-    time: current time
-  */
-EventManager.prototype.emitObject = function (event, object) {
-  var evObj = Object.create(object); // create inherited copy version so origin is untouched
-  evObj.event = event;     // augment with the event type
-  evObj.time = Date.now(); // augument with the time of the event
-  this.emit(event, evObj);
+EventManager.prototype.removeListener = function (event, listener) {
+  if (this.emitter) this.emitter.removeListener.apply(this.emitter, arguments);
 };
 module.exports = EventManager;
 module.exports.global = EventManager.create(); // create one top level emitter

package/lib/finalcb-first-task.js CHANGED Viewed

@@ -5,23 +5,22 @@ var util = require('util');
 var STATUS = require('./status.js');
 var VContext = require('./vcon.js');
+var EventManager = require('./event-manager.js');
 var OUTTASK_A_REQ = 'ast.outTask.a should be an array of string param names';
 function FinalCbFirstSuccTask(outTaskOptions) {
   var taskDef = outTaskOptions.taskDef;
-  var cbFunc = outTaskOptions.cbFunc;
-  var tasks = outTaskOptions.tasks;
-  var vCon = outTaskOptions.vCon;
-  var execOptions = outTaskOptions.execOptions;
-  var retValue = outTaskOptions.retValue;
-  if (typeof(cbFunc) !== 'function') throw new Error('callback is not a function');
+  if (typeof(outTaskOptions.cbFunc) !== 'function') throw new Error('callback is not a function');
   var self = this;
-  Object.keys(taskDef).forEach(function (k) { self[k] = taskDef[k]; });
-  this.f = cbFunc;
-  this.tasks = tasks;
-  this.vCon = vCon;
-  this.retValue = retValue;
+  for (var k in taskDef) {
+    if (true) self[k] = taskDef[k];  // if to make jshint happy
+  }
+  this.f = outTaskOptions.cbFunc;
+  this.tasks = outTaskOptions.tasks;
+  this.vCon = outTaskOptions.vCon;
+  this.retValue = outTaskOptions.retValue;
+  this.env = outTaskOptions.env;
 }
 function format_error(errmsg, obj) {
@@ -49,11 +48,15 @@ FinalCbFirstSuccTask.prototype.isReady = function () {
 FinalCbFirstSuccTask.prototype.exec = function (err) {
   if (!this.f) return;   //must have already been called
   if (err) {
+    this.env.error = err;
+    this.env.flowEmitter.emit(EventManager.TYPES.EXEC_FLOW_ERRORED, this.env);
     this.f.call(null, err); //call the final callback with the first error hit
   } else { // no error, call with args
     var vCon = this.vCon;
     var finalArgs = this.a.map(function (k) { return vCon.getVar(k); });
     finalArgs.unshift(null);   //unshift err=null to front
+    this.env.results = finalArgs;
+    this.env.flowEmitter.emit(EventManager.TYPES.EXEC_FLOW_COMPLETE, this.env);
     this.f.apply(null, finalArgs);
   }
   this.f = null;   // prevent multiple calls