jam 0.6.0 → 0.7.0

package/example/map.js

@@ -1,29 +0,0 @@
-
-var FILES = 'file1.txt,file2.txt,file3.txt'.split(',')
-  , jam = require('../lib/jam')
-  , fs = require('fs');
-
-// normal form
-var readFile = function(next, filename) { fs.readFile(filename, next); }
-  , catResult = function(next, result) {
-    process.stdout.write(result.join(''));
-    next();
-  };
-
-function normal(next) {
-  console.log("NORMAL FORM ::");
-  jam(jam.map(FILES, readFile))
-    (catResult)
-    (next);
-}
-
-function monad(next) {
-  console.log("MONAD FORM ::");
-  jam(jam.return(FILES))
-    (jam.map(readFile))
-    (catResult)
-    (next);
-}
-
-jam(normal)(monad)(function(e) { if (e) console.error(e); });
-

package/index.js

@@ -1,6 +0,0 @@
-
-// index.js - Main application entrypoint
-module.exports = process.env.JAM_COVER ?
-  require('./lib-cov/jam') :
-  require('./lib/jam');
-

package/lib/jam.js

@@ -1,295 +0,0 @@
-
-// lib/jam.js - Main JAM entrypoint
-module.exports = (function() {
-
-  var assert = require('assert'), tick = null;
-
-  // Find out if we have setImmediate and fallback to setTimeout if necessary.
-  tick = typeof setImmediate === 'function' ?
-    setImmediate :
-    function(func) { setTimeout(func, 0); };
-
-  // # INTERNAL HELPERS
-
-  // Function and arguments helpers.
-  var toArgs = function(args) { return Array.prototype.slice.call(args); };
-
-  function replaceHead(args, newHead) {
-    args = toArgs(args);
-    if (!args.length) return [newHead];
-
-    args[0] = newHead;
-    return args;
-  }
-
-  function bind(func, context) {
-    return function() { return func.apply(context, arguments); };
-  }
-
-  // Common assertions
-  function ensureFunc(func, argName) {
-    assert(typeof func === 'function', argName + ' argument missing or not a function');
-  };
-
-  function ensureNum(num, argName) {
-    assert(typeof num === 'number', argName + ' argument missing or not a number');
-  };
-
-  function ensureArray(arr, argName) {
-    assert(arr && typeof arr === 'object' && typeof arr.length === 'number',
-      argName + ' argument missing or does not looks like an array');
-  };
-
-  // ---
-
-  // # HELPERS
-
-  // Additional functions that adds to the original jam function.
-  function includeHelpers(func) {
-
-    // ## jam.identity()
-
-    // Simple function that passes the values it receives to the next function.
-    // Useful if you need a `process.nextTick` inserted in-between your call chain.
-    func.identity = function(next) {
-      function _identity(next) {
-        var args = arguments;
-        tick(function() {
-          next.apply(this, replaceHead(args, null));
-        });
-      }
-
-      // This function can also be passed to jam verbatim.
-      return (typeof next === 'function') ?
-        _identity.apply(this, arguments) :
-        _identity;
-    };
-
-    // ## jam.nextTick()
-
-    // Alias for `.identity`. Use when you need a `process.nextTick` inserted in-between
-    // your call chain.
-    func.nextTick = func.identity
-
-    // ## jam.return( [args...] )
-
-    // Returns a set of values to the next function in the chain. Useful when you want to
-    // pass in the next function verbatim without wrapping it in a `function() { }` just
-    // to pass values into it.
-    func.return = function() {
-      var args = toArgs(arguments);
-      return function(next) {
-        args.unshift(null);
-        next.apply(this, args);
-      };
-    };
-
-    // ## jam.null()
-
-    // Similar to `.identity` but absorbs all arguments that has been passed to it and
-    // forward nothing to the next function. Effectively nullifying any arguments passed
-    // from previous jam call.
-    // 
-    // Like `jam.identity`, this function can be passed to the jam chain verbatim.
-    func.null = function(next) {
-      function _null(next) { next(); }
-
-      return (typeof next === 'function') ? _null.call(this, next) : _null;
-    };
-
-    // ## jam.call( function, [args...] )
-
-    // Convenience for calling functions that accepts arguments in standard node.js
-    // convention. Since jam insert `next` as first argument, most functions cannot be
-    // passed directly into the jam chain, thus this helper function.
-    // 
-    // If no `args` is given, this function passes arguments given to `next()` call from
-    // previous function directly to the function (with proper callback) placement).
-    // 
-    // Use this in combination with `jam.return` or `jam.null` if you want to control the
-    // arguments that are passed to the function.
-    func.call = function(func) {
-      ensureFunc(func, 'function');
-
-      var args = toArgs(arguments);
-      args.shift(); // func
-
-      if (args.length) { // use provided arguments
-        return function(next) {
-          args.push(next);
-          func.apply(this, args);
-        };
-
-      } else { // use passed-in arguments during chain resolution
-        return function(next) {
-          args = toArgs(arguments);
-          args.shift(); // move next to last position
-          args.push(next);
-
-          func.apply(this, args);
-        };
-      }
-    };
-
-    // ## jam.each( array, iterator( next, element, index ) )
-
-    // Execute the given `iterator` function for each element given in the `array`. The
-    // iterator is given a `next` function and the element to act on. The next step in the
-    // chain will receive the original array passed verbatim so you can chain multiple
-    // `.each` calls to act on the same array.
-    // 
-    // You can also pass `arguments` and `"strings"` as an array or you can omit the array
-    // entirely, in which case this method will assume that the previous chain step
-    // returns something that looks like an array as its first result.
-    // 
-    // Under the hood, a JAM step is added for each element. So the iterator will be
-    // called serially, one after another finish. A parallel version maybe added in the
-    // future.
-    func.each = function(array, iterator) {
-      if (typeof array === 'function') {
-        iterator = array;
-        array = null
-      } else {
-        ensureArray(array, 'array');
-      }
-
-      ensureFunc(iterator, 'iterator');
-
-      return function(next, array_) {
-        var arr = array || array_;
-
-        // Builds another JAM chain internally
-        var chain = jam(jam.identity)
-          , count = arr.length;
-
-        for (var i = 0; i < count; i++) (function(element, i) {
-          chain = chain(function(next) { iterator(next, element, i); });
-        })(arr[i], i);
-
-        chain = chain(function(next) { next(null, arr); });
-        return chain(next);
-      };
-    };
-
-    // ## jam.map( array, iterator( next, element, index ) )
-
-    // Works exactly like the `each` helper but if a value is passed to the iterator's
-    // `next` function, it is collected into a new array which will be passed to the next
-    // function in the JAM chain after `map`.
-    // 
-    // Like with `each`, you can omit the `array` input, in which case this method will
-    // assume that the previous chain step returns something that looks like an array as
-    // its first result.
-    func.map = function(array, iterator) {
-      if (typeof array === 'function') {
-        iterator = array;
-        array = null;
-      } else {
-        ensureArray(array, 'array');
-      }
-
-      ensureFunc(iterator, 'iterator');
-
-      return function(next, array_) {
-        var arr = array || array_;
-
-        // Builds another JAM chain internally and collect results.
-        // TODO: Dry with .each?
-        var chain = jam(jam.identity)
-          , count = arr.length
-          , result = [];
-
-        for (var i = 0; i < count; i++) (function(element, i) {
-          chain = chain(function(next, previous) {
-            result.push(previous);
-            iterator(next, element, i);
-          });
-        })(arr[i], i);
-
-        chain = chain(function(next, last) {
-          result.push(last);
-          result.shift(); // discard first undefined element
-          next(null, result);
-        });
-
-        return chain(next);
-      };
-    };
-
-    // ## jam.timeout( timeout )
-
-    // Pauses the chain for the specified `timeout` using `setTimeout`. Useful for
-    // inserting a delay in-between a long jam chain.
-    func.timeout = function(timeout) {
-      ensureNum(timeout, 'timeout');
-
-      return function(next) {
-        var args = replaceHead(arguments, null);
-        setTimeout(function() { next.apply(this, args); }, timeout);
-      };
-    };
-
-    // TODO: noError() ? or absorbError()
-    return func;
-  };
-
-  // ---
-
-  // # JAM function
-
-  // Exported function starts the asynchronous call chain.
-  function jam(func, context) {
-    ensureFunc(func, 'function');
-
-    var steps = [];
-
-    // ##### Chain resolver.
-
-    // The resolver will execute all functions passed to the chain as soon as `nextTick`.
-    // Thus jam will not works across async context where the chain is not built all at
-    // once in a single event loop, which is not really a problem from my personal
-    // experience.
-    tick(function resolve(e) {
-      var args = Array.prototype.slice.call(arguments);
-
-      // Any errors passed to next() are (fast-)forwarded to the last function in the
-      // chain skipping any functions that's left to be executed.
-      if (e) return steps[steps.length - 1].apply(this, args);
-
-      // Any parameters given to next() are passed as arguments to the next function in
-      // the chain (except for errors, of course.)
-      var next = steps.shift()
-        , args = Array.prototype.slice.call(arguments)
-
-      if (steps.length) {
-        args.shift(); // error arg
-        args.unshift(resolve); // next() function
-      }
-
-      return next.apply(this, args);
-    });
-
-    // ##### Chain context continuation.
-
-    // Subsequent invocation of the function returned from the `jam` function simply adds
-    // the given function to the chain.
-    function continuable(func, context) {
-      ensureFunc(func, 'function');
-
-      if (context) { // TODO: Handle falsy things?
-        func = bind(func, context);
-      }
-
-      steps.push(func);
-      return continuable;
-    };
-
-    return includeHelpers(continuable(func, context));
-  };
-
-  // ---
-
-  return includeHelpers(jam);
-
-})();
-

package/test/helpers.js

@@ -1,271 +0,0 @@
-
-// test/helpers.js - Test JAM helper functions
-(function() {
-
-  var assert = require('chai').assert
-    , stub = require('sinon').stub;
-
-  var NON_ARR_OR_FUNCS = [undefined, null, 123, 'string', { }]
-    , NON_FUNCTIONS = NON_ARR_OR_FUNCS.concat([[]])
-    , NON_ARRAYS = NON_ARR_OR_FUNCS.concat([function() { }])
-    , NON_NUMS = [undefined, null, 'string', { }, function() { }, []];
-
-  var ITERABLES = ['each', 'map'];
-
-
-  // functions with multiple usage modes
-  describeModes = function(modes, tests) {
-    for (var mode in modes) (function(mode, code) {
-      var factory = new Function('return ' + code + ';');
-
-      describe(mode, function() {
-        before(function() { this.factory = factory; });
-        after(function() { delete this.factory; });
-
-        tests()
-      });
-    })(mode, modes[mode]);
-  };
-
-
-  describe('Helpers', function() {
-    before(function() { this.jam = require('../index'); });
-
-    describe('.identity function', function() {
-      describe('.nextTick alias', function() {
-        it('should be exported', function() {
-          assert.typeOf(this.jam.nextTick, 'function');
-          assert.equal(this.jam.nextTick, this.jam.identity);
-        });
-      });
-
-      it('should be exported', function() {
-        assert.typeOf(this.jam.identity, 'function');
-      });
-
-      var MODES =
-        { 'normal form'  : 'this.jam.identity'
-        , 'invoked form' : 'this.jam.identity()' };
-
-      describeModes(MODES, function() {
-        it('should calls the next function without any args when used standalone', function(done) {
-          this.jam(this.factory())
-            (function(next) { assert.lengthOf(arguments, 1); next(); })
-            (done);
-        });
-
-        it('should pass all the args to the next function when used in chain', function(done) {
-          this.jam(function(next) { next(null, 'one', 'two'); })
-            (this.factory())
-            (function(next, arg0, arg1) {
-              assert.equal(arg0, 'one');
-              assert.equal(arg1, 'two');
-              next();
-            })
-            (done);
-        });
-      });
-
-    }); // .identity
-
-    describe('.return function', function() {
-      it('should be exported', function() {
-        assert.typeOf(this.jam.return, 'function');
-      });
-
-      it('should calls the next function with the supplied values', function(done) {
-        this.jam(this.jam.return('one', 'two'))
-          (function(next, arg0, arg1) {
-            assert.equal(arg0, 'one');
-            assert.equal(arg1, 'two');
-            next();
-          })
-          (done);
-      });
-    }); // .return
-
-    describe('.null function', function() {
-      it('should be exported', function() {
-        assert.typeOf(this.jam.null, 'function');
-      });
-
-      var MODES =
-        { 'normal form'  : 'this.jam.null'
-        , 'invoked form' : 'this.jam.null()' };
-
-      describeModes(MODES, function() {
-        it('should calls the next function in the chain with no arguments', function(done) {
-          this.jam(function(next) { next(null, 1, 2, 3); })
-            (this.factory())
-            (function(next, arg) {
-              assert.isUndefined(arg);
-              next();
-            })
-            (done);
-        });
-      });
-    }); // .null
-
-    describe('.call function', function() {
-      it('should be exported', function() {
-        assert.typeOf(this.jam.call, 'function');
-      });
-
-      it('should throws if function argument missing or not a function', function() {
-        var me = this;
-
-        NON_FUNCTIONS.forEach(function(thing) {
-          assert.throws(function() { me.jam.call(thing); }, /func/i);
-        });
-      });
-
-      it('should calls the given function when no arguments given', function(done) {
-        var spy = stub().callsArg(0);
-        this.jam(this.jam.call(spy))
-          (function(next) { assert(spy.called); next(); })
-          (done);
-      });
-
-      it('should passes arguments to the function if arguments given', function(done) {
-        var spy = stub().callsArg(1);
-        this.jam(this.jam.call(spy, 'one'))
-          (function(next) { assert(spy.calledWith('one')); next(); })
-          (done);
-      });
-
-      it('should forwards arguments to `next()` from previous function if no arguments given', function(done) {
-        var spy = stub().callsArg(2);
-
-        this.jam(function(next) { next(null, 'one', 'two'); })
-          (this.jam.call(spy))
-          (function(next) { assert(spy.calledWith('one', 'two')); next(); })
-          (done);
-      });
-    }); // .call
-
-    describe('.timeout function', function() {
-      it('should be exported', function() {
-        assert.typeOf(this.jam.timeout, 'function');
-      });
-
-      it('should throws if timeout argument missing or not a number', function() {
-        var me = this;
-
-        NON_NUMS.forEach(function(thing) {
-          assert.throws(function() { me.jam.timeout(thing); }, /timeout/i);
-        });
-      });
-
-      it('should calls the next function after the specified timeout', function(done) {
-        this.jam(this.jam.timeout(1))(done);
-      });
-
-      it('should forwards arguments to `next()` from previous function', function(done) {
-        this.jam(this.jam.return('hello'))
-          (this.jam.timeout(1))
-          (function(e, hello) {
-            assert(hello === 'hello');
-            done()
-          });
-      });
-    });
-
-    describe('iterable functions', function() {
-
-      ITERABLES.forEach(function(func) {
-        describe('.' + func + ' function', function() {
-          it('should be exported', function() {
-            assert.typeOf(this.jam[func], 'function');
-          });
-
-          it('should throws if array argument not an array or function', function() {
-            var me = this;
-            NON_ARR_OR_FUNCS.forEach(function(thing) {
-              assert.throws(function() { me.jam[func](thing); }, /array/i);
-            });
-          });
-
-          it('should throws if iterator argument missing or not a function', function() {
-            var me = this;
-            NON_FUNCTIONS.forEach(function(thing) {
-              assert.throws(function() { me.jam[func]([1,2,3], thing); }, /iterator/i);
-            });
-          });
-        });
-      }); // iterables
-
-      var MODES =
-        { 'normal form':
-          'this.jam[arguments[0]].call(this.jam, arguments[2])'
-        , 'invoked form':
-          'this.jam[arguments[0]].call(this.jam, arguments[1], arguments[2])'
-        };
-
-      describeModes(MODES, function() {
-        ITERABLES.forEach(function(func) {
-          it('should calls iterator for each element in the given array serially', function(done) {
-            var elements = ['one', 'two', 'three']
-              , index = 0;
-
-            var check = function(next, element, index_) {
-              assert.equal(index_, index);
-              assert.equal(element, elements[index]);
-              index++;
-              next()
-            };
-
-            this.jam(this.jam.return(elements))
-              (this.factory(func, elements, check))
-              (done);
-          });
-
-          it('should forwards error properly when an iterator calls `next()` with an Error`', function(done) {
-            var err = new Error('test error')
-              , elements = ['one', 'two', 'three']
-              , index = 0;
-
-            var err = function(next, element, index_) {
-              next(index_ < 2 ? undefined : err);
-            }
-
-            this.jam(this.jam.return(elements))
-              (this.factory(func, elements, err))
-              (function(e) {
-                assert.equal(e, err); // should be forwarded here
-                done()
-              });
-          });
-        });
-      }); // describeModes
-
-    }); // iterables
-
-    describe('.each function', function() {
-      it('should pass original array to next() when done', function(done) {
-        var elements = [1, 2, 3];
-
-        this.jam(this.jam.each(elements, this.jam.identity))(function(next, result) {
-          assert.equal(elements, result);
-          next()
-        })(done);
-      });
-    }); // .each
-
-    describe('.map function', function() {
-      it('should collects iterator result and pass to next()', function(done) {
-        var elements = [1, 2, 3];
-
-        this.jam(this.jam.map(elements, function(next, element, index) {
-          return next(null, element * 2);
-        }))(function(next, result) {
-          for (var i = 0; i < elements.length; i++) {
-            assert.equal(elements[i] * 2, result[i]);
-          }
-          next()
-        })(done);
-      });
-    }); // .map
-
-  });
-
-})();