react 0.0.0-f77c7b9d7 → 0.0.1

package/LICENSE

@@ -1,6 +1,4 @@
-MIT License
-
-Copyright (c) Facebook, Inc. and its affiliates.
+Copyright (c) 2011 Jeff Barczewski
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal
@@ -9,13 +7,13 @@ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 copies of the Software, and to permit persons to whom the Software is
 furnished to do so, subject to the following conditions:
 
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
 
 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

package/README.md

@@ -1,13 +1,138 @@
-# `react`
+# React.js
 
-React is a JavaScript library for creating user interfaces.
+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.
 
-The `react` package contains only the functionality necessary to define React components. It is typically used together with a React renderer like `react-dom` for the web, or `react-native` for the native environments.
+This async flow control module is initially designed to work with Node.js but 
+is planned to be extended to browser and other environments.
 
-**Note:** by default, React will be in development mode. The development version includes extra warnings about common mistakes, whereas the production version includes extra performance optimizations and strips all error messages. Don't forget to use the [production build](https://reactjs.org/docs/optimizing-performance.html#use-the-production-build) when deploying your application.
+It takes inspiration from several projects including: 
 
-## Example Usage
+ - Tim Caswell and Elijah Insua's [conductor](https://github.com/creationix/conductor) - [Article](http://howtonode.org/step-of-conductor)
+ - Caolan McMahon's [async](https://github.com/caolan/async)
 
-```js
-var React = require('react');
-```
+## Goals
+
+ - Improved error and exception handling
+ - Provide useful stack traces and context information for easier debugging
+ - Minimize boilerplate code needed for working with asynchronous functions
+ - Make code more readable and easier to understand which should translate to less defects
+ - Provide the right level of abstraction to make it easier to refactor code, without being too magical
+ - Allow the mixing of pure functions, method calls, and callback style functions in the flow
+ - Minimize the need to customize your code simply to use async flow control. The use of a flow control module ideally should not affect the way you write your code, it should only help take over some of the burden.
+
+## Concept
+
+Borrowing heavily from Tim and Elijah's ideas for conductor, this async flow control module provides a way to construct a flow from a collection of functions or methods (referred to as _tasks_ in this module). It allows dependencies to be defined between the tasks so they can run in parallel as their dependencies are satisfied. React can us both variable dependencies and task dependencies. 
+
+As tasks complete, React watches the dependencies and kicks off additional tasks that have all their dependencies met and are ready to execute. This allows the flow to run at maximum speed without needing to arbitrarily block tasks into groups of parallel and serial flow.
+
+To reduce the boilerplate code needed and improve error handling, React automatically provides callback functions for your asynchronous code. These React-provided callback functions perform these steps:
+
+ 1. check for error and handle by calling outer callback function with this error after augmenting it with additional context information for easier debugging
+ 2. save the callback variables into a context for future reference
+ 3. call back into React (and it will kick off additional tasks that are now ready to go)
+
+## Design
+
+ - Optional parse step to create flow AST (TODO allow pluggable parsers to allow many interfaces)
+ - Validate the flow AST - determine if dependencies can all be met as defined such that flow will complete (TODO)
+ - Execute the flow AST
+
+## Examples
+
+ 1. [Direct AST](#directAST)
+ 2. [Using Simple DSL](#simpleDSL)
+
+<a name="directAST"/>
+### Example directly using AST
+
+    var react = require('react').react;
+
+    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 r = react();
+    r.ast.inputNames = ['filename', 'uid', 'outDirname', 'cb'];
+    r.ast.taskDefs = [
+      { f:loadUser,          a:['uid'],               cb:['user'] },
+      { f:loadFile,          a:['filename'],          cb:['filedata'] },
+      { f:markdown,          a:['filedata'],          ret:['html'] },
+      { f:prepareDirectory,  a:['outDirname'],        cb:['dircreated'] },
+      { f:writeOutput,       a:['html', 'user'],      cb:['bytesWritten'],   after:['prepareDirectory'] },
+      { f:loadEmailTemplate, a:[],                    cb:['emailmd'] },
+      { f:markdown,          a:['emailmd'],           ret:['emailHtml'] },
+      { f:customizeEmail,    a:['user', 'emailHtml'], ret:['custEmailHtml'] },
+      { f:deliverEmail,      a:['custEmailHtml'],     cb:['deliveredEmail'], after:['writeOutput'] }
+    ];
+    r.ast.finalOutputNames = ['html', 'user', 'bytesWritten'];
+
+    r.exec("hello.txt", 100, 'outHello', useHtml);
+    r.exec("small.txt", 200, 'outSmall', useHtml);
+
+<a name="simpleDSL"/>
+### Example using simple DSL interface
+
+    var react = require('react').react;
+
+    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 r = react('filename, uid, outDirname, cb').define(
+        loadUser,         'uid              -> err, user',
+        loadFile,         'filename         -> err, filedata',
+        markdown,         'filedata         -> returns html',
+        prepareDirectory, 'outDirname       -> err, dircreated', 
+        writeOutput,      'html, user       -> err, bytesWritten', { after:prepareDirectory },
+        loadEmailTemplate,'                 -> err, emailmd',
+        markdown,         'emailmd          -> returns emailHtml',
+        customizeEmail,   'user, emailHtml  -> returns custEmailHtml',
+        deliverEmail,     'custEmailHtml    -> err, deliveredEmail', { after: writeOutput }
+    ).callbackDef('err, html, user, bytesWritten');
+
+## Status
+
+ - 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.
+
+## License
+
+ - [MIT license](http://github.com/jeffbski/react/raw/master/LICENSE)
+
+## Contributors
+
+ - Author: Jeff Barczewski (@jeffbski)
+
+## Contributing
+
+ - Source code repository: http://github.com/jeffbski/react
+ - Ideas and pull requests are encouraged  - http://github.com/jeffbski/react/issues
+ - You may contact me at @jeffbski or through github at http://github.com/jeffbski

package/lib/react.js

@@ -0,0 +1,228 @@
+'use strict';
+
+var util = require('util');
+
+var reactOptions = {
+  debugOutput: false
+};
+
+/**
+   @example
+   var r = react('filename, uid, cb').define(
+     loadUser,   'uid               -> err, user',
+     loadFile,   'filename          -> err, filedata',
+     markdown,   'filedata          -> returns html',
+     prepareDirectory, 'outDirname  -> err, dircreated', 
+     sendOutput, 'html, user        -> err, html, bytesWritten', {after:prepareDirectory}
+   ).callbackDef('err, html, user, bytesWritten');
+
+   r.exec(filename, uid, function(err, html, user, bytesWritten){
+     //use html
+   });
+   
+ */
+
+function fName(fn){
+  return (typeof(fn) === 'string') ? fn : fn.name;
+}
+
+function formatErrorMeta(err){
+  if (!err.meta) return;
+  var vcon = err.meta.vcon;
+  var task = err.meta.task;
+  return '\n\n' +
+      'Error occurs in Task function: ' + fName(task.f) + '(' + task.a.join(',') + ')\n\n' + 
+      'Variable Context: \n' +
+      util.inspect(vcon) + '\n\n' +
+      'Task Source:\n\n' +
+      task.f.toString() + '\n\n'; //TODO need to pretty print function, gets collapsed
+}
+
+function augmentError(err, meta){
+  if (typeof(err) === 'string' ) { err = new Error(err); } //props will be lost on non-objects
+  var origMsg = err.toString();
+  err.meta = meta;
+  err.toString = function() { return origMsg + formatErrorMeta(err); };
+  return err;
+}
+
+function splitTrimFilterArgs(commaSepArgs){ //parse 'one, two' into ['one', 'two']
+  return commaSepArgs.split( ',' )            //split on commas
+    .map(function(s){ return s.trim(); }) //trim
+    .filter(function(s){ return (s); });  //filter out empty strings
+}
+
+function parseInOutDef(inOutDef){ //'a, b -> err, c, d' into { inDef: ['a','b'], outDef: ['c', 'd'] }
+  var match = /^([^-]*)(->)?\s*(er{0,2}\s*,)?(.*)$/.exec(inOutDef);
+  if (match) {
+    return { inDef: splitTrimFilterArgs(match[1]),
+             outDef: splitTrimFilterArgs(match[4]) };
+  }
+  throw "error parsing in/out def: "+inOutDef;
+}
+
+function nameTasks(tasks){ //name tasks that are not already named, validation done elsewhere, ret map
+  var namesMap = tasks.reduce(function(map, t){
+    if (t.name) { map[t.name] = t; }
+    return map; }, {});
+  tasks.forEach(function(t, idx){
+    if (!t.name) { //not already named
+      var name = fName(t.f);
+      if (!name || namesMap[name]) name = ''+name+'_'+idx; //if empty or already used, postfix with _idx 
+      t.name = name;
+      namesMap[name] = t;
+    }
+  });
+  return namesMap;
+}
+
+function parseTaskDefs(arrArgs){ // [fun, strArgsCbArgs, optObj]
+  var taskDefs = [];
+  var CHECK_RETURNS_RE = /^returns?\s+(\w+)\s*;?$/;
+  while(arrArgs.length){
+    var fn = arrArgs.shift();
+    var strArgsCbArgs = arrArgs.shift();
+    var optObj = (typeof(arrArgs[0]) === 'object') ? arrArgs.shift() : { };
+    if (typeof(strArgsCbArgs) !== 'string') throw "eror parsing taskdef, expected str, got:"+strArgsCbArgs;
+    var inOutDef = parseInOutDef(strArgsCbArgs);
+    var taskDef = { f:fn, a:inOutDef.inDef, cb:inOutDef.outDef };
+    Object.keys(optObj).forEach(function(k){ taskDef[k] = optObj[k]; })
+    if (taskDef.after) {
+        if (!Array.isArray(taskDef.after)) { taskDef.after = [taskDef.after]; } //ensure arr
+        taskDef.after = taskDef.after.map(function(a){ return fName(a); }); 
+    }
+    var matchReturn = CHECK_RETURNS_RE.exec(taskDef.cb[0]);
+    if (matchReturn) { // found return(s) varname, so change this to return type fn
+      delete taskDef.cb; taskDef.ret = matchReturn[1]; } // del cb, add ret:varname 
+    taskDefs.push( taskDef );
+  }
+  return taskDefs;
+}
+
+
+function react(inputDef){
+  inputDef = Array.prototype.slice.call(arguments).join(', '); //convert 'a', 'b', 'c' into 'a, b, c'
+  var reactObj;
+  var inOutDef = parseInOutDef(inputDef); 
+  var ast = { inputNames: inOutDef.inDef,
+              finalOutputNames: inOutDef.outDef, //this might be set later
+              taskDefs: [] };                    //set in define()    
+  var STATUS = { READY: 'ready',  RUNNING: 'running', ERRORED: 'errored', COMPLETE: 'complete' };
+
+  function define(arg1, arg2, argN){
+     ast.taskDefs = ast.taskDefs.concat(parseTaskDefs(Array.prototype.slice.call(arguments)));
+     nameTasks(ast.taskDefs); //set names in ast.taskDefs so that ast can be inspected before exec
+     return reactObj;
+  }
+
+  function callbackDef(argDef){   //define the callback output names
+    argDef = Array.prototype.slice.call(arguments).join(', '); //convert 'a', 'b', 'c' into 'a, b, c'
+    argDef = ( argDef && /^\s*->/.test(argDef)) ? argDef : '-> '+argDef;  //prefix with -> before parse
+    var inOutDef = parseInOutDef(argDef); //should be '-> a,b,c'
+    ast.finalOutputNames =  inOutDef.outDef;  
+    return reactObj;
+  }
+
+  function exec(arg1, arg2, argN){
+    var args = Array.prototype.slice.call(arguments);
+    var cbFinal = args.pop(); //pop off final callback from end
+    var vCon = { }; //create variable context
+    args.forEach(function(x, idx){ vCon[ast.inputNames[idx]] = x; });
+    var firstError;     //will be set to the err of first task that errors
+    var contExec;       //function defined later
+    var tasksByName = {}; //set later, by calling nameTasks
+
+    function handleTaskError(task, err){
+      task.status = STATUS.ERRORED;
+      if (!firstError) { //no prev error, only calling final callback with error once
+        var errWithMeta = augmentError(err, {task:task, vcon:vCon});
+        firstError = errWithMeta; //save this, stop other tasks from being launched
+        cbFinal.call(null, errWithMeta); //call the final callback with the first error hit
+      }
+    }
+
+    function createCallback(task) {
+      return function(err, arg0, arg1, argn){
+        var args = Array.prototype.slice.call(arguments,1);
+        if(err){ handleTaskError(task, err); return; } //handle error and return, we are done
+
+        //no error, save callback args to vCon context, then continue execution
+        task.cb.forEach(function(k, idx){ //save cb args to v context
+          vCon[k] = (args[idx] !== undefined) ? args[idx] : null; //upgrade any undefined to null
+        });
+        task.status = STATUS.COMPLETE;
+        if (reactOptions.debugOutput) console.log('in callback: %s cb:', fName(task.f), args, vCon);
+        contExec();
+      };
+    }
+
+    var tasks = ast.taskDefs.map(function(ot){  //create working task copies
+      var t = Object.create(ot);
+      if(t.cb) t.cbFun = createCallback(t); //if is callback type fn, create callback
+      return t;
+    });
+    tasksByName = nameTasks(tasks); //remap names to exec task copies instead of taskDefs
+
+
+    function execTask(t){
+      t.status = STATUS.RUNNING;
+      var args = t.a.map(function(k){ return vCon[k]; }); //get args from vCon
+      if (t.cbFun) args.push(t.cbFun); //push custom callback to back if fn uses cb
+      if (reactOptions.debugOutput) console.log('starting task: %s', fName(t.f), args);
+      try {
+        var func;
+        var bindObj = null; //start as global object
+        if (typeof(t.f) === 'string') { //object method call
+          var match = /(\w+)\.(\w+)/.exec(t.f);
+          if (match) {
+            var objName = match[1];
+            var methName = match[2];
+            bindObj = vCon[objName];
+            func = bindObj[methName];
+          }
+          if (!func) throw new Error('Object or method not found: '+t.f);
+        } else { //function call
+          func = t.f;
+        }
+        var ret = func.apply(bindObj, args);
+        if (t.ret) {                      //if non-cb fn/method, 
+          vCon[t.ret] = ret;              //  save retval
+          t.status = STATUS.COMPLETE;     //  mark complete
+          contExec();                     //  continue since no callback to run this
+        }                     
+      } catch (e) { handleTaskError(t, e); }    //catch and handle the task error, calling final cb
+    }      
+    
+    contExec = function contExec(){
+      if (firstError) { return; } //stop execution, we already hit an error
+      if (tasks.every(function(t){ return (t.status === STATUS.COMPLETE); })) { //all completed
+        //we are done, call final callback
+        var finalArgs = ast.finalOutputNames.map(function(k){ return vCon[k]; });
+        finalArgs.unshift(null); //unshift err=null to front
+        cbFinal.apply(null, finalArgs);
+        return;
+      }
+      var tasksReady = tasks.filter(function(t, idx, arr){ //if we are here then we stil have tasks to run
+        return !t.status &&                                                   // filter for not started AND
+               t.a.every(function(k){ return (vCon[k] !== undefined); }) &&   // all dep vars defined AND
+               (!t.after ||                                                   // (no dep tasks OR 
+                t.after.every( function(n){ return tasksByName[n].status === STATUS.COMPLETE; })); //alldone
+      });
+      tasksReady.forEach(function(t){ t.status = STATUS.READY; }); //set ready before call, no double exec
+      tasksReady.forEach(function(t){ execTask(t); });
+    };
+    contExec(); //now kick off the execution for exec()
+  }
+
+  reactObj = {
+    define: define,
+    callbackDef: callbackDef,
+    exec: exec,
+    ast: ast,
+  };
+  
+  return reactObj;
+}
+
+module.exports.react = react;
+module.exports.reactOptions = reactOptions;

package/package.json

@@ -1,39 +1,13 @@
 {
   "name": "react",
-  "description": "React is a JavaScript library for building user interfaces.",
-  "keywords": [
-    "react"
-  ],
-  "version": "0.0.0-f77c7b9d7",
-  "homepage": "https://reactjs.org/",
-  "bugs": "https://github.com/facebook/react/issues",
-  "license": "MIT",
-  "files": [
-    "LICENSE",
-    "README.md",
-    "build-info.json",
-    "index.js",
-    "cjs/",
-    "umd/",
-    "jsx-runtime.js",
-    "jsx-dev-runtime.js"
-  ],
-  "main": "index.js",
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/facebook/react.git",
-    "directory": "packages/react"
-  },
-  "engines": {
-    "node": ">=0.10.0"
-  },
-  "dependencies": {
-    "loose-envify": "^1.1.0",
-    "object-assign": "^4.1.1"
-  },
-  "browserify": {
-    "transform": [
-      "loose-envify"
-    ]
-  }
-}
+  "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.0.1",
+  "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" }, 
+  "licenses": [{ "type": "MIT", "url" : "http://github.com/jeffbski/react/raw/master/LICENSE" }],
+  "main": "react",
+  "engines": { "node": "~v0.4.12" },
+  "dependencies": {},
+  "devDependencies": {}
+}